Publishing and versions
On this page
A theme is an npm package. You give it a version, build it, and publish it to the BizzPocket registry,
npm.bizzpocket.com. A store then runs one exact version of it. This page covers how to pick the
version number, how to publish, how a store gets your version, and what to check before you ship.
Contents: Versions · What is a breaking change · Build · The package.json · Publish · How stores get a version · Checklist
Versions
The theme's version is the version in its package.json. It is the only place you write it. The
build copies it into the theme's manifest and into every default layout (themeVersion), so do not put
themeVersion in layouts/*.json yourself (theme-config.md).
Use semantic versioning: MAJOR.MINOR.PATCH.
| Change | Bump | Example |
|---|---|---|
| A fix that changes nothing a store has saved | patch | 0.4.0 → 0.4.1 |
Something new that every saved store keeps working with: a new block, a new field with a default, a new token, a new style |
minor | 0.4.1 → 0.5.0 |
| Anything in the list below | major | 0.5.0 → 1.0.0 |
While a theme is below 1.0.0, many teams bump the minor number for a breaking change
(0.5.0 → 0.6.0). That is allowed by semver, but say so in your changelog.
A version that is published can never be published again with different contents. To fix a mistake, publish the next version.
What is a breaking change
Stores save their pages as layouts: a list of blocks, each with a type and the seller's values in
props. A breaking change is one that makes a saved layout show something different from what the
seller saved. These are breaking:
- Renaming a block folder. The folder name is the block's
type, and saved layouts refer to the block by it. After a rename, every saved copy of the old block finds no block and is skipped: it disappears from the page. The same goes for deleting a block, and for changing thetypeorvariantof a migrated block (migrate.md). - Removing a field. The seller's saved value is still in the layout, but nothing reads it. Their setting is lost.
- Changing a field's kind (for example
f.texttof.number, orf.collectiontof.products). A saved value that does not fit the new kind is not an error: it is replaced by the field's default. The page still renders, but the seller's setting is gone. - Renaming a field key. It is a removal plus an addition: the old value is lost.
- Changing a default. A block whose saved
propsdo not have that key reads the default. So every store that never touched the field changes its look on the next render. Tighteningmin,max,maxLengthor the options of anf.selectis breaking for the same reason: saved values outside the new rule are clamped or replaced. - Removing a token from
overridable, or renaming a token. Store owners' brand settings for it stop applying (theme-config.md). - Changing the theme's
id. It is a different theme.
These are not breaking:
- adding a block, a style, a token or a vertical;
- adding a field that has a
default, or anoptionalfield; - changing a block's
render, CSS ordata()while its fields keep their meaning; - changing your theme's default layouts in
layouts/. They are used only for pages a store has not saved yet. Saved pages keep their own copy.
When you must break something, keep the old block or field working for one major version if you can:
keep the old folder and add the new one next to it, or keep reading the old key in render.
Build
Build, type-check and test before every publish:
bunx bizzpocket build
bunx tsc -p .
bun testbuild writes dist/ and prints the size report (cli.md).
Read the data column: a block that turned runtime since the last version is slower for every store.
The first-party themes run all three in prepublishOnly, so bun publish refuses to publish a theme that
does not build:
"scripts": {
"build": "bizzpocket build --target both",
"check-types": "tsc --noEmit -p tsconfig.json",
"test": "bun test",
"prepublishOnly": "bun run build && bun run check-types && bun run test"
}The package.json of a published theme
init already names the package @bizzpocket/theme-<id>, but it is "private": true (so a stray
bun publish is refused) and has only what local work needs. Before you publish, fill it in. This is the shape the first-party SDK 3 themes use (packages/themes/toyshop), with
my-theme as the id:
{
"name": "@bizzpocket/theme-my-theme",
"version": "1.0.0",
"private": false,
"type": "module",
"sideEffects": ["**/*.css", "**/*.client.js"],
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
"./styles": "./dist/styles.css",
"./blocks.json": "./dist/blocks.json",
"./templates.json": "./dist/templates.json",
"./package.json": "./package.json"
},
"files": ["dist", "README.md", "CHANGELOG.md"],
"publishConfig": { "access": "restricted" }
}Keep the peerDependencies and devDependencies that init wrote.
| Field | Why |
|---|---|
name |
The theme marketplace accepts only @bizzpocket/theme-<id>. Any other name is refused (Theme package name must be "@bizzpocket/theme-<id>"). Use the same <id> as theme.config.ts. |
private: false |
bun publish refuses a private package. |
exports["./styles"] |
The build needs it to point at ./dist/styles.css (STYLES_EXPORT_MISSING otherwise). |
files |
Ship dist. Your source folders are not needed: everything that runs is in dist/. Add locales if your theme has one. |
publishConfig.access |
restricted: only accounts with access to the registry can install it. |
Publish
What needs the BizzPocket team today. There is no self-serve sign-up for theme developers yet. Two things are done by the BizzPocket team on request:
- A verified publisher profile. Only a
VERIFIEDpublisher can submit a theme (NO_PUBLISHER,PUBLISHER_NOT_VERIFIEDotherwise). Ask your BizzPocket contact or platform support. - A registry token that may publish to
npm.bizzpocket.com. Your BizzPocket contact issues it.
What you can do yourself, end to end:
bunx @bizzpocket/cli init my-theme # a new theme (cli.md#start-a-theme-init)
cd my-theme && bun install
bun run dev # bizzpocket dev --mock: preview with sample data
bunx bizzpocket check # what will break or run slow in a store
bunx bizzpocket package # check + build into one .tgz and its manifest
bunx bizzpocket publish --dry-run # validate the package and print what would be uploadedThe CLI has a publish command, but today it only does a dry run: it packages the theme (or takes
--package <file.tgz>), validates the archive against its manifest and prints what it would upload and
where. Nothing is sent. Without --dry-run it exits 1 with an explanation: the upload endpoint is not
live yet (cli.md). Then hand the package (the .tgz and its
.manifest.json) to the BizzPocket team, or, once the team has verified your publisher profile and given
you a registry token, publish and submit it yourself with the steps below.
1. Name the registry token. Keep the token in your shell as NPM_TOKEN, and only name it in
.npmrc (tokens.md):
2. Check that the version is new:
bun pm view @bizzpocket/theme-my-theme versions --registry https://npm.bizzpocket.com3. Look at what will be packed, then publish:
bun publish --dry-run
bun publish --registry https://npm.bizzpocket.com --access restricted--dry-run lists the files without uploading anything. Check that dist/ is there and that no .env,
key file or test fixture is.
4. Check it arrived:
bun pm view @bizzpocket/theme-my-theme@1.0.0 --registry https://npm.bizzpocket.comThe output ends with .tarball (the package's URL) and .integrity (its sha512-… checksum). You
need both to submit the version to the marketplace (below).
In CI, write the .npmrc from a secret, publish, and delete the file at the end. BizzPocket's own SDK
packages are published this way by .github/workflows/publish-theme-packages.yml: by hand, only from
main, and skipping any version that is already on the registry.
How stores get a version
A store runs one version of one theme. Publishing a new version does not change any store by itself. There are two ways a version reaches stores.
Marketplace themes
This is the path for a theme you make.
- Become a verified publisher. The BizzPocket team sets this up on request (see Publish);
there is no self-serve sign-up yet. Without it a submission is refused with
NO_PUBLISHERorPUBLISHER_NOT_VERIFIED. - Submit the version. In the seller dashboard: Themes → Submissions → Submit a theme. For a new
theme, give its name, description and preview image; for a new version of a theme you already own,
pick the theme. Then give the version (semver), the tarball URL and its
sha512checksum (frombun pm view, step 4 above), and the package'spackage.json. An ed25519 signature of the tarball is optional. A version that was already submitted for that theme is refused (DUPLICATE_VERSION). If the team publishes the package for you, they submit it too. - Review. The version starts as
PENDING_REVIEW. A BizzPocket staff member reviews it and moves it toAPPROVED,REJECTED(with a reason, shown to you) orBLOCKED. You can follow it under Themes → Submissions.
What happens after a staff member approves a version:
- Staging. Approval queues the version for staging: it is turned into a runtime artifact and
published as
@bizzpocket-runtime/theme-<id>with the same version, and its checksum is recorded with the version. A theme that fails staging because of its own code isBLOCKED. - Stores install it. The approved theme is listed in the seller dashboard's theme gallery. A store
owner adds it (the install is
STAGINGuntil it is ready, thenINSTALLED) and then applies it. A store gets the latest approved version that has a runtime artifact: the highest semver, then the most recently published. That version is pinned to the store. A store that already uses the theme stays on its pinned version until its owner installs and activates another one. Activating a version that is notAPPROVED, or not yet staged, is refused (VERSION_NOT_APPROVED,NOT_STAGED).
The storefront downloads the artifact of the store's pinned version and checks it against the recorded checksum before it runs it. A file that does not match is never served. So a version, once approved, cannot be changed under the stores that use it.
An approved version can later be DEPRECATED (no new installs) or BLOCKED. Either change tells the
storefront to drop that version from its cache.
First-party themes
The themes in the BizzPocket repository (packages/themes/*) are bundled into the storefront. The
list is BUNDLED_THEMES in apps/storefront-v2/theme-bundle.config.mjs. For these, the storefront
renders the version that was installed when it was built, and a new version reaches stores when the
storefront is next deployed. A bundled theme wins over a runtime artifact of the same theme.
If a store's theme cannot be loaded (an unknown theme, an artifact that cannot be fetched in time), the
store renders the fallback theme (FALLBACK_THEME_ID, today fashionbee) instead of an error page.
Pre-publish checklist
-
versioninpackage.jsonis bumped, by the rule in Versions, and not on the registry yet. - Every breaking change is in a major version, and listed in
CHANGELOG.md. - No block folder was renamed or removed, unless this is a major version.
- No field was removed, renamed or changed kind, and no default changed, unless this is a major version.
-
nameis@bizzpocket/theme-<id>, and<id>matchesidintheme.config.ts. -
privateisfalse, andpublishConfig.accessisrestricted. -
exports["./styles"]is./dist/styles.css, andfilesincludesdist. -
bunx bizzpocket buildpasses with no warning you have not read. - The size report has no block that became
runtimeor grewclient gzby surprise. -
bunx tsc -p .andbun testpass. -
bunx bizzpocket dev --mock --prodrenders every page type your theme has layouts for. -
layouts/global.jsonhas a header and a footer, andlayouts/*.jsonhave nothemeVersion. -
bun publish --dry-runlistsdist/and nothing secret (no.env,.npmrc, keys). - The registry token is in your shell or CI secrets, not in a file.
Next: migrate.md if you have a 2.x theme, or the changelog.