BizzPocket

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 the type or variant of 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.text to f.number, or f.collection to f.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 props do not have that key reads the default. So every store that never touched the field changes its look on the next render. Tightening min, max, maxLength or the options of an f.select is 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 an optional field;
  • changing a block's render, CSS or data() 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:

bash
bunx bizzpocket build
bunx tsc -p .
bun test

build 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:

json
"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:

json
{
  "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 VERIFIED publisher can submit a theme (NO_PUBLISHER, PUBLISHER_NOT_VERIFIED otherwise). 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:

bash
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 uploaded

The 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:

bash
bun pm view @bizzpocket/theme-my-theme versions --registry https://npm.bizzpocket.com

3. Look at what will be packed, then publish:

bash
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:

bash
bun pm view @bizzpocket/theme-my-theme@1.0.0 --registry https://npm.bizzpocket.com

The 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.

  1. 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_PUBLISHER or PUBLISHER_NOT_VERIFIED.
  2. 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 sha512 checksum (from bun pm view, step 4 above), and the package's package.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.
  3. Review. The version starts as PENDING_REVIEW. A BizzPocket staff member reviews it and moves it to APPROVED, REJECTED (with a reason, shown to you) or BLOCKED. You can follow it under Themes → Submissions.

What happens after a staff member approves a version:

  1. 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 is BLOCKED.
  2. Stores install it. The approved theme is listed in the seller dashboard's theme gallery. A store owner adds it (the install is STAGING until it is ready, then INSTALLED) 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 not APPROVED, 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

  • version in package.json is 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.
  • name is @bizzpocket/theme-<id>, and <id> matches id in theme.config.ts.
  • private is false, and publishConfig.access is restricted.
  • exports["./styles"] is ./dist/styles.css, and files includes dist.
  • bunx bizzpocket build passes with no warning you have not read.
  • The size report has no block that became runtime or grew client gz by surprise.
  • bunx tsc -p . and bun test pass.
  • bunx bizzpocket dev --mock --prod renders every page type your theme has layouts for.
  • layouts/global.json has a header and a footer, and layouts/*.json have no themeVersion.
  • bun publish --dry-run lists dist/ 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.