The CLI
On this page
- Install
- Start a theme: init
- Add pieces: add, diff, add-to-layout
- Copy a piece from the registry: add
- See what changed upstream: diff
- Put a block on a page: add-to-layout
- Preview: dev
- With sample data: dev --mock
- Another language: --locale
- With a real store: dev --store
- What happens when you save
- As production serves it: dev --prod
- Other dev flags
- Check your token: whoami
- Build and read the size report: build
- Reading the table
- Options
- The output folder and the .bizzpocket-build marker
- What is in dist/
- Move global CSS into the blocks: css-split
- Check a theme: check
- Rules
- Budgets
- Configuration
- The --json output
- In CI
- Make a package: package
- Publish: publish
- Migrate a 2.x theme: migrate
- Type your blocks, layouts and messages: typegen
- Getting help
bizzpocket is the one tool you use to make a theme. It creates the theme folder, copies building
pieces into it, previews it in your browser, and builds it. This page walks through each command by
task. Every flag of every command is listed in reference/cli.md.
Contents: Install · Start a theme · Add pieces · Preview · Check your token · Build · Check a theme · Migrate a 2.x theme · Getting help
Install
The CLI runs on Bun 1.3 or newer. It does not run on Node: its bin starts with
#!/usr/bin/env bun, and it uses Bun's own server, file and gzip functions.
It is the npm package @bizzpocket/cli on the BizzPocket registry, npm.bizzpocket.com. Tell Bun where
that registry is with an .npmrc in your home folder or the theme folder (registry.md;
the token line is explained in tokens.md):
@bizzpocket:registry=https://npm.bizzpocket.com
//npm.bizzpocket.com/:_authToken=${NPM_TOKEN}You do not need to install it globally. Create a theme with bunx:
bunx @bizzpocket/cli init my-themeEvery theme lists @bizzpocket/cli as a dev dependency, so after bun install in the theme folder,
bunx bizzpocket <command> runs the theme's own copy. The new theme also has two scripts:
bun run dev (bizzpocket dev --mock) and bun run build (bizzpocket build).
Which version is on the registry. As of 2026-11-14 the registry has @bizzpocket/cli 0.3.0,
with @bizzpocket/theme 0.3.0, @bizzpocket/sir 0.3.0, @bizzpocket/theme-runtime 0.3.0,
@bizzpocket/theme-sdk 2.25.0, @bizzpocket/blocks 0.4.2 and @bizzpocket/fonts 0.1.0. Every
command on this page is in CLI 0.3.0, check included. The 0.2.0 and 0.3.0 marks say which
release added a command or flag, so an older copy pinned in a theme may lack it: check the
@bizzpocket/cli version in the theme's package.json and see the changelog.
Only run themes you trust. dev and build run the theme's code on your machine, in the same
process as the CLI, with your environment (tokens included).
Start a theme: init
bunx @bizzpocket/cli init my-themecreated /home/you/my-theme
next: cd my-theme && bizzpocket dev --mock (sample data; --store <slug> for a real store)init copies the blank starter into a new folder (its .gitignore is stored in the CLI package as gitignore, because npm drops a file with that name when it publishes a package, and init puts the dot back). The starter is a small, complete store written the way the SDK
recommends, so read it as the reference for a clean theme: it passes bizzpocket check --strict with no warning, its
types have no error, and its pages need under 7 KB of JavaScript and 2 KB of CSS (gzip).
my-theme/
README.md the five commands, what each folder is
package.json scripts, the `bizzpocket.check` settings, the @bizzpocket/* versions
theme.config.ts id, name, tokens, i18n (en, hi), SEO title template
tsconfig.json includes blocks/ and types/
eslint.config.mjs theme-safety lint for blocks/
.gitignore .vscode/settings.json
styles/global.css tokens, resets and shared rules only
locales/en.json hi.json every visible string; the kit's strings under `kit`
types/ written by `typegen`, committed on purpose
blocks/ header (menu, search island), hero (font and range fields), product-grid (static data,
ProductCard), product-listing (load, browse helpers, FilterRail, Pager), product-detail
(product, Gallery, Price, head with JSON-LD), product-reviews, search-results, cart (cartModel
and useCartView), content-page, footer, not-found; each with its own <block>.css
layouts/ global, home, shop, category, product, search, cart, content, not_foundpackage.json has these scripts: dev (bizzpocket dev --mock; dev:mock is the same), build, check, check:ci
(bizzpocket check --strict), typegen, package, lint (eslint blocks) and typecheck (tsc --noEmit).
eslint.config.mjs lints blocks/** and src/** for banned imports and globals and raw fetch(). The starter
asks for @bizzpocket/cli, @bizzpocket/theme and @bizzpocket/sir at ^0.3.0, the first release that has check
and typegen.
types/ is committed, not ignored: the editor then knows block props, layout files and ctx.t keys straight after a
clone, and CI can run bizzpocket typegen --check to catch a stale copy. Run bizzpocket typegen after you add a field,
a block or a string. The starter's .vscode/settings.json maps types/layout.schema.json onto layouts/*.json.
- The folder name is the theme's id. It must be lowercase with dashes.
init My_Themestops withINVALID_THEME_ID: directory name "My_Theme" is invalid; use a lowercase-kebab name such as "my-theme". - The folder must be new or empty.
initnever writes into a folder that has files: it printsinit: <dir> is not empty; init only creates a theme in a new or empty directoryand exits 1. - The package is named
@bizzpocket/theme-<id>, the only name the theme marketplace accepts, and is"private": trueso it cannot be published by accident. Set"private": false(and the other fields) when you publish (publishing.md). --blankis the default. You can leave it out.
To start from an existing theme instead, use --from:
bunx @bizzpocket/cli init my-copy --from ../my-theme--from copies the theme's source and leaves out dist, node_modules, .bizzpocket, .git, .npmrc,
.env files, key files (.pem, .key, .p12) and symlinks. The copy is a new theme named after its
folder: the package becomes @bizzpocket/theme-my-copy, id in theme.config.ts becomes my-copy,
and so does themeId in layouts/*.json.
Then install:
cd my-theme
bun installWhat each file is for: first-block.md.
Add pieces: add, diff, add-to-layout
Copy a piece from the registry: add
bunx bizzpocket add money-priceadded money-priceadd copies the source of a registry item (a block, component, data helper or trait) into your theme
and records it in bizzpocket.json. Once copied, the code is yours. Running add again for an item you
have not changed does nothing harmful.
bunx bizzpocket add money-price group # several at once
bunx bizzpocket add nopeUNKNOWN_ITEM: no registry item named "nope"If you changed a copied file, add refuses to replace it:
MODIFIED_FILE: components/money-price/money-price.tsx has local changes; re-run with --overwrite to replace itAdd --overwrite only when you want the registry's version back. The list of items, where each kind is
copied to, --trust-registry and --allow-proxy are in registry.md.
See what changed upstream: diff
bunx bizzpocket diff # every installed item
bunx bizzpocket diff money-price # one itemdiff prints nothing when your copy matches the registry. When it differs, - lines are the
registry's and + lines are yours:
--- a/components/money-price/money-price.tsx
+++ b/components/money-price/money-price.tsx
@@ -9,3 +9,4 @@
export function MoneyPrice({ amount, currency, className }: MoneyPriceProps) {
return <Money amount={amount} currency={currency} className={className} />;
}
+// minediff only reads. An item you never installed gives NOT_INSTALLED: "hello" is not installed in this theme.
Put a block on a page: add-to-layout
A block shows on a page when a layout lists it. add-to-layout appends one instance of a block to
layouts/<page>.json, with a new id and the fields' defaults:
bunx bizzpocket add-to-layout featured-collection
bunx bizzpocket add-to-layout featured-collection --page productadded featured-collection to layouts/home.json (id e1d551ef-8e2a-420c-b8b8-1bfbf459cea0)
added featured-collection to layouts/product.json (id a5a57b2d-6b1e-435d-9e7f-787b3551865b)--pagedefaults tohome. If the layout file does not exist, it is created.- The block must exist as
blocks/<name>/<name>.tsx. Otherwise:blocks/nope/nope.tsx does not exist in /home/you/my-theme. layouts/global.jsonholds the header and footer regions, soadd-to-layoutdoes not edit it:layouts/global.json has regions (header, footer): edit it by hand, see theme-config.md(theme-config.md).
0.2.0: --parent <id> puts the new block inside a container block (one with f.blocks(), such as
the registry's group) instead of at the end of the page:
bunx bizzpocket add group
bunx bizzpocket add-to-layout group
bunx bizzpocket add-to-layout hello --parent 60923653-d6d2-468a-82b3-6234476ced82added group to layouts/home.json (id 60923653-d6d2-468a-82b3-6234476ced82)
added hello to layouts/home.json inside 60923653-d6d2-468a-82b3-6234476ced82 (id 6840f95e-902c-47e2-bcf4-8bdcb37c9cd5)A container is always added with children: []. Pointing --parent at a block that is not a container
is refused:
--parent 6f1d1f0e-9c1a-4a43-8d6a-1d2b6a0a1001 is a hello block, which has no f.blocks() field; only a container (such as group) holds blocksMore on containers: group.md.
Preview: dev
dev builds the theme, serves it at http://127.0.0.1:4321, and rebuilds and reloads the page each
time you save. It renders with the same page code the live storefront uses. You need exactly one of
--mock or --store.
With sample data: dev --mock
bunx bizzpocket dev --mock[dev] block server B client gz css gz data
------------------- -------- --------- ------ ------
featured-collection 1490 0 213 static
hello 292 0 0 none
total 0 216
[dev] built in 127 ms
bizzpocket dev: http://127.0.0.1:4321 mock data (sample toy store, signed-in sample shopper, no API)--mock serves a sample toy store from a mock API inside the CLI. It needs no store, no token and no
network. The store has 30 sample products ("Wooden Rainbow Stacker", "Classic Train Set"...), and every
collection slug returns all of them, paged (page, limit: four pages of 8), sorted (newest,
price-asc, price-desc) and filtered (priceMin, priceMax, inStock) as asked. productSearch
matches the words of q in the titles. It also has two sample offers (promotions()), four filters
(facets()) and a signed-in sample shopper with addresses, orders and a wishlist (customer(),
orders(), ...).
bunx bizzpocket dev --mock-guest--mock-guest (it implies --mock) shows the signed-out view: every shopper helper returns null.
Use it to test the account and login states of your blocks. See
More helpers.
The mock sends money the way the real API does: amount is a number (499), not a string. A test in the CLI checks
every mock answer against the SDK's result types, so Price, ProductCard and productJsonLd print the same here as
on a store.
Another language: --locale
bunx bizzpocket dev --mock --locale hi
bunx bizzpocket dev --store my-store --locale hi--locale <tag> shows every page in that locale instead of the store's own, for this dev server only: nothing is
written to the store. The tag must be one of the theme's declared locales (the locales/*.json files, or i18n.locales
in theme.config.ts). Anything else stops dev with one line that lists them:
--locale fr: this theme declares en, hiUse it to see the second language in your blocks and in the kit's own strings (kit.* keys), and to check a long
translation against your layout.
The storefront's form endpoints (/api/newsletter, /api/customer/auth, the PIN code lookup...) get
canned answers too, so forms can be tried; with --store, only the PIN code lookup is forwarded
(forms.md lists them and says why).
With a real store: dev --store
export BIZZPOCKET_DEV_TOKEN=bpdt_... # from the store owner; never in a file in the theme folder
bunx bizzpocket dev --store my-storebizzpocket dev: http://127.0.0.1:4321 store=my-store api=https://api.dev.bizzpocket.com--store takes the store's slug and reads that store's real products, menus and prices. It needs a
developer token in BIZZPOCKET_DEV_TOKEN. The store owner makes one in the seller dashboard under
Settings → Developers. It starts with bpdt_, reads only that store's public data, and expires. What
it can and cannot do, and how to keep it safe: tokens.md.
Without a token, dev stops before building:
BIZZPOCKET_DEV_TOKEN is not set. Ask the store owner for a developer token (seller dashboard → Settings → Developers) and export it in your shell, not in the theme folder. Without one, `bizzpocket dev --mock` previews with sample data.Developer tokens need CLI 0.2.0 or later (the registry has 0.3.0). CLI 0.1.0 only accepted the BizzPocket team's internal token.
--api <url> points dev at another API (default https://api.dev.bizzpocket.com). The token is sent
to that host, so it must be https; plain http is allowed only for localhost:
--api must be https (plain http only for localhost): the dev token is sent with every requestWhen the host is not bizzpocket.com (or a subdomain) or a loopback address, dev and whoami print one
warning: --api <host> is not a bizzpocket.com host: your developer token is sent there ... line first. Use such a
host only for a server you run yourself.
What happens when you save
dev watches everything a theme is made of: blocks/, components/, src/, styles/, layouts/,
locales/, theme.config.* and package.json. It skips dist/, node_modules/ and editor temp files.
A burst of saves gives one rebuild, and a save during a rebuild runs in the next one.
Hot updates
The browser updates in place where it can, and reloads only when it has to. The terminal says which one happened and why.
| You change | The browser |
|---|---|
styles/** or any .css file |
swaps the stylesheets in place. No reload, no flash, scroll and island state stay |
a block's render, data or fields, components/**, src/** |
fetches the page again and swaps only the blocks whose HTML changed. An island whose element is unchanged keeps its state, in the swapped block too |
locales/** |
the same: every block whose text changed is swapped |
layouts/*.json |
the same, and blocks may be added or removed in <main> |
| island code (a file an island imports) | reloads the page: new code cannot keep old state. The page says "island code changed" |
theme.config.* |
reloads the page and says why |
package.json |
no rebuild. A notice says to restart dev if you changed a dependency |
A change that the page cannot take safely (a block was added outside a layout edit, or a swapped block holds a changed island and the runtime cannot start it again) also reloads, with the reason on screen and in the terminal.
If a rebuild fails, the last good build keeps serving, a red box at the bottom of the page shows the error in plain words with the file and line, and the terminal says:
[dev] rebuild failed, still serving the last good build:
PARSE_FAILED: /home/you/my-theme/blocks/hello/hello.tsx: Unexpected token — see docs/theme-sdk/troubleshooting.md#parse_failedA page that fails to render shows the same box with the HTTP status. Fix the file and save again. The box goes away on the next good build, and the dev server never stops on a bad save.
The dev endpoints live under /_bp/dev/ on the dev server's own address (events and client.js). They
listen on 127.0.0.1 only and refuse any request whose Host or Origin is not the dev server's own, so a web
page you visit cannot drive the server. No developer token is sent to the browser or printed. A build never
contains the dev client. The build output of a dev run goes to .bizzpocket/dev/ (removed when dev stops),
never to dist/.
Sample data for content pages and reviews
dev --mock and dev --mock-guest answer page() and pages() (three sample pages: about-us,
shipping-policy, returns; any other handle is a 404 and page() resolves to null), give every product a
rating and 2 to 4 reviews (every third product has none, to try the empty state), and answer the two
operations predictive search calls, productSearch and categoryTree.
As production serves it: dev --prod
bunx bizzpocket dev --mock --prodbizzpocket dev (--prod): http://127.0.0.1:4321 mock data (sample toy store, no API)--prod builds once with a minified server bundle and React's production build, and serves it with no
file watcher and no reload script. Use it to check how the page really behaves and how big it really is.
Restart it after a change.
Other dev flags
| Flag | What it does |
|---|---|
--port <n> |
The local port. Default 4321. 0 picks a free one. |
--dir <path> |
The theme folder. Default .. |
dev listens only on 127.0.0.1, answers only GET and HEAD, and refuses requests whose Host is
not localhost or 127.0.0.1 (so a web page cannot reach it through DNS tricks).
Check your token: whoami
0.2.0. Before you start dev --store, check the token:
bunx bizzpocket whoami --store my-storestore: My Store (my-store)
token: Pixel Studio (bpdt_a1B2c3D4…)
expires: 2027-01-30It prints the token's store, the name the owner gave the token, the first characters of the token and the expiry date. It never prints the whole token. When something is wrong, it says what:
| You see | Meaning |
|---|---|
BIZZPOCKET_DEV_TOKEN is not set. ... |
Export the token in your shell. |
BIZZPOCKET_DEV_TOKEN is not a developer token (those start with bpdt_), so whoami cannot check it. |
The variable holds something else, for example the team's internal token. |
The developer token is not valid: it was revoked, it expired, or it was mistyped. ... |
Ask the store owner for a new one. |
This token is for the store "other-store", not "my-store". ... |
Use the right --store, or a token from the right store. |
Too many requests with this token; wait a minute and try again. |
Over 120 requests a minute. |
https://api.dev.bizzpocket.com answered 404 |
That API has no whoami endpoint (it runs an older backend). Ask BizzPocket, or try dev --store directly. |
whoami takes --api <url> like dev, with the same https rule.
Build and read the size report: build
bunx bizzpocket buildblock server B client gz css gz data
------------------- -------- --------- ------ ------
featured-collection 1490 0 213 static
group 2875 0 523 none
hello 292 0 0 none
total 0 628
built /home/you/my-theme/distbuild writes everything to dist/ and never rewrites your source. A failed build puts the previous
dist/ back.
Reading the table
| Column | What it is |
|---|---|
block |
The block's folder name. |
server B |
Bytes of the block's server code in the server bundle. It is never sent to the browser. |
client gz |
Gzipped JavaScript sent to the browser for the block's 'use client' files. 0 means the block sends no JavaScript (interactivity.md). |
css gz |
Gzipped CSS of the block. Only pages that use the block load it. |
data |
none (no data), static (the page fetches it in one call, from a template made at build time) or runtime (worked out on every request). See data.md. |
The total row adds up client gz, and gives the gzipped size of the whole styles.css.
0.2.0: under the table, the build says why each runtime block is runtime, with the file and line:
block server B client gz css gz data
------------------- -------- --------- ------ -------
best-sellers 552 0 0 runtime
featured-collection 1490 0 213 static
hello 292 0 0 none
total 0 216
why runtime (see docs/theme-sdk/data.md, "Why is my block runtime?"):
blocks/best-sellers/best-sellers.tsx:11 ternary (?:) in data() [data-not-static]The word in brackets is the reason. Each reason and its fix: data.md.
The build also prints warnings, for example
warning: layouts/product.json has no block with role "product-detail"; the editor expects one
(theme-config.md). A warning does not fail the build.
Options
| Flag | What it does |
|---|---|
--target next |
The bundle for the current storefront host (Next.js), plus dist/styles.css. |
--target bun |
The bundle for the Bun renderer (what dev uses), in dist/bun/. |
--target both |
Both. The default. |
--dir <path> |
The theme folder. Default .. |
--json |
0.2.0. Print the size report as JSON instead of the table. Warnings go to stderr, so bizzpocket build --json | jq works. |
--out <folder> |
Write everything to <folder> instead of <theme>/dist (the theme folder stays untouched). See below. |
bunx bizzpocket build --json{
"blocks": [
{
"type": "best-sellers",
"serverBytes": 552,
"clientGzipBytes": 0,
"cssGzipBytes": 0,
"data": "runtime",
"reason": "data-not-static",
"detail": "ternary (?:) in data()",
"at": "blocks/best-sellers/best-sellers.tsx:11"
},
{
"type": "featured-collection",
"serverBytes": 1490,
"clientGzipBytes": 0,
"cssGzipBytes": 213,
"data": "static"
}
],
"totalClientGzip": 0,
"totalCssGzip": 216
}The same report is always written to dist/size-report.json, so CI can check it without --json.
The output folder and the .bizzpocket-build marker
A rebuild into an output folder deletes only what an earlier build wrote there. Every folder the build creates gets a
marker file, .bizzpocket-build, that records the theme id and the list of top-level entries that build wrote.
The rules:
-
An empty or missing folder is fine. A folder with files and no marker is refused (
--out), unchanged:refusing to write into /path/to/folder: it has files that this build did not create; choose an empty folder or delete it yourself -
A folder with a marker is rebuilt only for the same theme id. Another theme's marked folder is refused with one line (
it was built for theme "a", not "b") and left as it is. -
Only the entries the marker lists are deleted. If the folder holds a top-level entry the marker does not list (a file you added,
mine.txt), the build refuses and names it. A marker you wrote by hand has no list, so it protects the folder the same way: it is never emptied. The marker has aformat: 2 is{format, theme, entries}; format 1 ({format, theme}) lists nothing, so what the folder holds is unknown and the build asks for an empty folder. -
The path is resolved first (symlinks followed), for the theme and the output folder. The theme folder, a parent of it and a folder inside the theme other than under
dist/or.bizzpocket/are refused. -
The theme's own
dist/(and the.bizzpocket/folderdevuses) belong to the CLI: adist/with no marker is adopted by the first build, which replaces only the files a build writes (index.js,styles.css,blocks.json,bun/, ...). Anything else indist/stays, on that build and on every later one. -
The previous output is kept aside while the build runs, removed on success, put back when the build fails: in
<folder>.prev-<pid>, or in a new name when that path is already taken by something that is not this theme's own leftover (it is never reused or deleted). A copy a crashed build left behind is removed by the next build, only if it carries the marker. -
package,check,typegenanddevbuild into temporary folders they create themselves (also with the marker) and remove only those. The marker is not part of a package.
What is in dist/
| File | What it is |
|---|---|
index.js, index.d.ts |
The theme for the Next.js host, and its types. |
styles.css |
All the theme's CSS. package.json must export it as ./styles. |
bun/ |
The Bun renderer's server bundle, its client chunks and per-block CSS. |
blocks.json |
The catalogue the page editor reads: every block, its fields and defaults. |
templates.json |
The data templates for static blocks, and the default layouts. |
size-report.json |
The size report. |
When a build fails, the message names the error code and links to its fix in troubleshooting.md.
Move global CSS into the blocks: css-split
A theme's global stylesheet ships on every page. The dependable way to shrink it is for each block to own its CSS in its
own file (blocks/<name>/<name>.css, which the build already ships per block). css-split finds the rules that can move
and writes the move into a copy, so you review a diff and prove it before you take it.
bizzpocket css-split [--dir <theme>] [--plan | --write --out <folder> [--include-likely]] [--list N] [--json]--plan (the default) writes nothing. It prints, per block, the rules of styles/global.css that could move, in four groups:
| Group | Meaning |
|---|---|
| safe | one block owns every class in the selector and the build's order proof holds (the same proof as css: { split: true }) |
| likely | one block owns every class, but the order guard held it back: a later rule that could hit the same element sits in another file. The reason (the later rule) is printed |
| shared | several blocks can carry the classes; the rule stays global |
| unknown | no block names the class: dead CSS, or a class set by content or script |
Rules with no class to own (:root, element selectors, nested rules) and at-rules the reader does not open (@layer,
@container) stay global and are counted. The plan ends with the gzip size of the global sheet and of every default
page (global plus that page's blocks) before, after the safe moves, and after safe plus likely.
--write --out <folder> writes a copy of the theme (never into the theme folder) with the safe rules, or with
--include-likely the likely ones too, moved into the blocks' CSS files and removed from styles/global.css. Moved
rules go before the block's own rules, in their original order, inside their @media / @supports wrappers; a block
without a CSS file gets blocks/<name>/<name>.css. A block whose first CSS file lies outside its folder, or is shared
with another block, keeps its rules global (listed as likely). The moved CSS is the build's output, formatted: comments of
the source are not carried over. node_modules is linked into the copy so it builds. The --out folder must be new, empty or
an earlier copy of the same theme.
Safe moves are proved by the build's own rules; likely moves are not. Prove either with the parity check:
bun packages/cli/scripts/css-parity.ts --before packages/themes/shosy --after <copy> [--widths 390,768,1440] [--pages home,cart] [--url product=/products/x] [--chrome <path>] [--json]
Each side is a theme folder (built here for the Bun renderer) or an existing build folder. Both are served by the Bun
renderer with the CLI's mock data. For every default layout page the script requires the HTML of both to be identical
apart from stylesheet links, inline <style> and the CSP nonce, then opens both in headless Chromium at each width
(scripts off, fonts blocked, images stubbed, other hosts blocked, animations frozen at their start, reduced motion, UTC)
and compares the computed style of every element and of its ::before / ::after for about 120 properties (layout,
typography, colour, border, transform, visibility) plus the element's rectangle. A difference prints the element path,
the property, both values and the rule that won in each build. Exit 1 on any difference, 2 when no Chromium is found
(--chrome, $CHROME_PATH, the Puppeteer cache and system paths are tried; nothing is installed). State a script sets
after load is not compared.
The default layouts and default mock data show only the markup the defaults switch on (a hero's arrows need two or more slides), so widen the run:
bun packages/cli/scripts/css-parity.ts --before <theme> --after <theme> --variants <dir> [--variant a,b] [--no-default] [--force-states] [--state-attrs <regex>] [--state-classes <regex>] [--max-states N]--variants <dir>: each*.jsonthere is a variant:page(a path),layouts(per page type:{ "replace": { "blocks": [...] } }or{ "patch": [{ "type" | "id", "props", "replaceProps", "hidden" }] }),answers(per mock operation such asproductDetail,storeProfile,navigationMenu,customerOrders:{ "replace" }or{ "patch" }, deep-merged),expect(selectors that must be in the DOM of both builds: a variant without a marker is refused, and a missing marker fails the run), optionalexpectAbsentandwidths. Both builds get the same variant, each from its own mock and renderer pair on free loopback ports. The same options exist onstartMockApi(layouts,answers; default behaviour unchanged). Shosy's are inpackages/themes/shosy/__tests__/fixtures/css-parity-variants/.--force-states(scripts still off): for one element of each tag + class group amonga, button, input, select, textarea, summary, [tabindex], [role=button], forces:hover,:focus+:focus-visibleand:activethrough the DevTools protocol and compares the element, its descendants and their::before/::after. It also reads every selector of both builds' sheets, derives the states they style ([aria-expanded="true"],[aria-selected],[aria-current],[aria-pressed],[aria-invalid],[data-state|open|active],[open],[hidden],:checked,:disabled,.is-*,.has-*,*--open,*--active, and:hover/:focus-withinon non-interactive elements), finds the elements that could hold each state, applies it (or its opposite when already on), compares the subtree (the parent's for sibling combinators) and undoes it. Transitions are finished before reading. Differences print asDIFF page [variant] @width {state}: element.- The browser is always closed and its profile folder removed, on success, failure, timeout, SIGINT and SIGTERM; its debugging port is a free loopback port and
--remote-allow-originsis never passed. - Not covered: state a script sets (client islands that render only after hydration, form errors), hover on elements that are not shown, and pseudo-classes other than those above.
To prove that moving CSS between files did not change which of two rules wins (static, covers every page, not only the ones a browser renders):
bun packages/cli/scripts/css-order-check.ts --before <styles.css | build dir | baseline.json> --after <same> [--src <theme dir>]... [--allow <file.json>] [--json]
bun packages/cli/scripts/css-order-check.ts --per-page --before <theme> --after <theme> # the Bun target, each default layout
bun packages/cli/scripts/css-order-check.ts --before <build dir> --write-baseline <out.json>It lists each pair of rules whose order changed, that can style one element with the same weight and share a property, with the winner before and after. Exit 1 when the winner changes for a shared property with different values; same-value overlaps are info.
Check a theme: check
0.3.0. check is in the published CLI 0.3.0 (see Install).
bizzpocket check reads your theme and tells you what will go wrong or run slow, before a store sees it.
It reads SDK 3 themes: a folder with no theme.config.ts is reported as an SDK 2 theme, with a pointer to
bizzpocket migrate.
It checks the layouts against your blocks, the data and size cost of each page, and the lint setup.
It never changes your theme: the build runs in a throw-away copy (.bizzpocket-check-*, next to the theme
folder, or in the OS temp folder when that folder is read-only), which is deleted when the check ends, also
after an error or Ctrl-C. A copy left by a crashed run is removed by the next run.
bizzpocket check # the theme in the current folder
bizzpocket check --dir ../my-theme
bizzpocket check --strict # warnings also make the exit code 1 (use this in CI)
bizzpocket check --verbose # also print the info findings
bizzpocket check --json # only { findings, summary } on stdoutThe exit code is 1 when there is an error (or, with --strict, a warning), otherwise 0. Info findings never
fail. A theme folder that does not exist stops with theme folder not found: <path>.
Warnings and errors print grouped by level. Findings of one rule that differ only by a name or number print
once, with the list of files. Info findings are hidden; one line says how many (--verbose shows them).
--json always has one entry per finding, info included.
Rules
| Rule | Level | What it means | Fix |
|---|---|---|---|
layout/unknown-block |
error | A layout names a block the theme does not have. | Fix the type, or add the block. |
layout/unknown-prop |
warning | A node sets a prop the block has no field for. | Remove it, or add the field. |
layout/invalid-prop |
error | A prop value breaks its field (wrong type, out of range, not an option, rich text over its length cap, which drops the whole value). Text over maxLength is a warning: the reader cuts it. |
Use a value the field accepts. |
layout/nesting |
error | A block sits where its parent does not allow it (f.blocks({ allow, max })). |
Move it, or change allow. |
layout/duplicate-id |
error | Two nodes in one layout share an id. |
Give each node its own UUID. |
layout/missing-id |
error | A node has no id. |
Add "id": "<uuid>". |
layout/missing-region |
error | layouts/global.json has no header or no footer region. |
Add the region. |
layout/missing-page |
info | The theme has no layout for some of the twelve commerce pages (listed in layouts.md). | Add the layout files when you need them. |
layout/unsafe-url |
error | A link or URL prop uses javascript: or another unsafe scheme, also inside rich text (the sanitizer removes that link). |
Use https:, mailto:, tel: or a path. |
layout/unknown-variant |
error | A variantId names a variant the theme does not define; the page shows the default variant. |
Use a defined variant, or remove variantId. |
layout/placeholder |
warning | A prop still holds text such as "Lorem ipsum". | Write the real text. |
layout/unknown-font |
warning | An f.font() prop in a layout holds an id that is not in the font catalog (or that the field does not offer); the block uses the field default. The message names it. |
Use a catalog font id. |
layout/out-of-range |
warning | An f.range() prop in a layout is outside min/max or off its step; the block clamps it. The message names the value it becomes. |
Use a value inside the bounds, on a step. |
i18n/missing-key |
warning | A locales/<locale>.json lacks keys of the default locale's file (kit.* keys are exempt). build and dev print it as a warning and still succeed; the shopper sees the default locale's text for that key. |
Translate the keys. |
i18n/extra-key |
warning | A locale file has keys the default locale does not. | Delete them, or add them to the default file. |
i18n/placeholder-mismatch |
warning | A key uses different {placeholders} than the default locale's text. |
Use the same placeholders. |
i18n/unknown-key |
warning | A literal t('a.b') in a block or a file it imports that no locale file and no kit string defines. |
Add the key, or fix it. |
i18n/hardcoded-string |
warning | JSX text, or aria-label, title, alt or placeholder, written in English in the code, in a theme that declares more than one locale. Info when the theme has one locale but already calls t(); a theme with one locale and no t() is not checked. One finding per file. Strings in {'text'} and in a template literal without ${} between tags count like JSX text. Skipped: text with no word of three letters, URLs and paths, one-word identifiers and class names, <code>, <script>, <style>. |
Use t('key') and add the key to the locale files. |
i18n/physical-css |
warning | The theme declares a right-to-left locale (ar, he, fa, ur...) and a stylesheet uses margin-left, padding-right, left:, text-align: left, float: right and the like. One finding per file, with the count. |
Use margin-inline-start, inset-inline-start, text-align: start, float: inline-start. |
seo/head-on-runtime-block |
info | A block has head() and load(), so the page shell waits for its data. |
Put head() on a static block. |
seo/canonical-rejected |
warning | A block's head() returns a canonical that is not a path or an https URL; the head core drops it. |
Return a path such as /products/x. |
seo/image-rejected |
warning | A block's head() returns an image URL that is not https or root-relative; the head core drops it. |
Use an https URL or a root-relative path. |
seo/conflicting-head |
warning | Two or more blocks on one page layout (with the global one) set a title, or a canonical, in head(). |
Keep it in one block. |
seo/duplicate-jsonld |
warning | One page emits JSON-LD of the same @type twice (two head() or a head() and a body <JsonLd>). |
Emit it once, from head(). |
seo/body-jsonld-duplicate |
warning | A block returns JSON-LD from head() and also renders <JsonLd>. |
Keep the one in head(). |
seo/missing-title |
info | The product, category, collection, policies or pages layout has no block that sets a title in head(). Only for themes that use head() somewhere. |
Return { title } from head(). |
theme/state-between-requests |
warning | A module-level let/var that a function assigns, or a module-level object, array, Map or Set that a function changes in place with a key or value that can come from the request (a parameter named or typed as ctx, props, route, params, store, or a local computed from one), in a file the server runs for a block (found through relative imports; 'use client' files and what only they import are skipped). One process renders many stores, so the value leaks between requests. A Map, array or object written only with constants or a pure function's own arguments (a memo) is an info note, not a warning. Not reported: WeakMap and WeakSet (keys are held weakly; keying one by the request object is the safe pattern), values never written, frozen objects, lookup tables, React cache(), writes at the top of a module, shadowed names, writes through an alias. |
Compute the value per request (inside load, data or render), use cache(), or freeze it. |
perf/font-budget |
warning | The f.font() fields of the blocks on one page ask for more than two fonts or four font files (font and weight). System fonts are free. |
Use one heading and one body font; limit weights. |
perf/load-block |
warning, or info | A block uses load(), so each page that shows it makes its own server request. A static data() can read route.page and route.sort for products(), and route.q and route.page for search(). It cannot read route.filters (never mapped into products()). The finding is info (the recommended shape for a filtered listing) when the load() reads route.filters, hands the route to a @bizzpocket/theme/browse helper, or reads a q, page or sort that none of the ops it queries (ctx.query('<op>')) can take from data(). Otherwise it is a warning that names the data() form; the message lists the built-in needs (products, product, related, categories, menu, store, home, search, gql). The check reads the function's code and keeps the warning when it cannot tell. |
Use data() with a built-in need when one covers the data, with the route values passed as page.route.page / .sort / .q (data.md). A listing that follows the URL's filters keeps load(). |
perf/shopper-load |
info | A block with a shopper role (account, order-list, order-detail, wishlist, login, signup, order-return, order-cancel, cart, checkout) or category account uses load(). That is the right tool; the page is served private. |
Nothing. |
perf/runtime-data |
warning | data() could not be made static; the message says why. |
Remove the cause the message names. |
perf/client-budget |
warning | Client JavaScript is over a budget (theme, block or page). | Cut islands, or lazy-load them. |
perf/css-budget |
warning | CSS is over a budget (theme, block or page). | Remove unused CSS. |
perf/renderer-need |
info | data() has a need only the renderer resolves, so the block is runtime. |
For reading. |
perf/page-summary |
info | Per page: how many of its blocks are none, static or runtime, and whether the page needs a data request. It shows no sizes. | For reading. |
theme/config |
error | theme.config.ts or package.json is unusable. |
See theme-config.md. |
theme/lint-coverage |
warning | No ESLint config, a config whose files globs leave out blocks/, or a lint script that runs eslint on paths without blocks/. A script with no path (eslint -c eslint.config.mjs) is judged by the config's files only. |
Use the starter's eslint.config.mjs and "lint": "eslint blocks src". |
theme/size-limit-config |
warning | .size-limit.json points at a file that does not exist, or counts server bundles (dist/**/*.js includes dist/index.js and dist/bun/server.js, which never reach a browser). |
Measure only dist/bun/client/*.js and dist/styles.css, or drop the file and use check as the size gate. |
theme/sdk2-import |
info | Files still import @bizzpocket/theme-sdk (SDK 2). |
See migrate.md. |
check/perf-skipped |
info | The build failed, so the perf/* rules did not run. |
Fix the build errors, run again. |
check/fs-error |
error | A file system problem stopped the check (for example no permission). | Fix the permission or folder named in the message. |
check/unknown-rule, check/config |
warning | The bizzpocket.check block of package.json names a rule that does not exist, or has a bad value. |
See Configuration below. |
Any other build failure is shown as build/<code> (for example build/invalid-catalog) with a link to its fix in
troubleshooting.md. A finding with no file shows an empty file.
Budgets
Sizes are gzip. The defaults and where they come from:
| Budget | Default | Flag | Source |
|---|---|---|---|
| Client JS, whole theme | 50 KB | --max-client-kb |
The measured client totals of the BizzPocket themes are 12 to 41 KB; 50 leaves room. |
| Client JS, one block | 10 KB | --max-block-client-kb |
images.md, performance budget. |
| Client JS, one page | 30 KB | --max-page-client-kb |
The same table. |
| CSS, whole theme | 20 KB | --max-css-kb |
The stylesheet budget the themes' own size checks use. |
| CSS, one block | 7 KB | --max-block-css-kb |
No published number: half the page budget. |
| CSS, one page | 14 KB | --max-page-css-kb |
images.md: up to 14 KB the Bun storefront inlines the CSS. |
A page's CSS is the global stylesheet part plus the CSS of the blocks on that page. When no block has CSS of its own, a theme over its CSS budget gets one finding, not one per level.
Configuration
Turn rules off, change their level, set budgets or ignore files in the theme's package.json:
{
"bizzpocket": {
"check": {
"rules": { "layout/placeholder": "off", "perf/load-block": "info", "layout/unknown-prop": "error" },
"budgets": { "clientTotalKb": 60, "cssPageKb": 16 },
"ignore": ["layouts/policies.json", "blocks/legacy-banner"]
}
}
}rules: a rule id and"off","info","warn"or"error".build/<code>rules can be set too. An id that does not exist is itself a warning (check/unknown-rule).budgets: the keys of the--jsonsummary.budgetsobject (clientTotalKb,clientBlockKb,clientPageKb,cssTotalKb,cssBlockKb,cssPageKb). A flag on the command line wins over the file.ignore: files, folders or globs; findings in them are dropped.
The --json output
{
"findings": [
{ "rule": "layout/unknown-prop", "severity": "warning", "file": "layouts/home.json", "line": 12, "message": "...", "fix": "..." }
],
"summary": {
"errors": 0, "warnings": 1, "infos": 3,
"byRule": { "layout/unknown-prop": 1 },
"budgets": { "clientTotalKb": 50, "clientBlockKb": 10, "clientPageKb": 30, "cssTotalKb": 20, "cssBlockKb": 7, "cssPageKb": 14 }
}
}A finding has rule, severity (error, warning or info), file (relative to the theme, "" when none),
message and fix ("" when there is nothing to do), and line (a whole number) only when the rule can point at one.
summary.byRule counts findings per rule. The numbers in summary count the findings in findings.
In CI
check is the size gate of the starter theme, so you do not need a second tool such as size-limit.
The starter has these scripts:
{ "check": "bizzpocket check", "check:ci": "bizzpocket check --strict", "lint": "eslint blocks src --no-error-on-unmatched-pattern" }bizzpocket check --strict --max-client-kb 40 # fail the job on any warning or error
bizzpocket check --json | jq '.summary' # counts per level and rule
bizzpocket check --json | jq -r '.findings[] | select(.severity=="error") | "\(.file): \(.message)"'Make a package: package
0.3.0. Checks the theme, builds it into a temporary folder (the theme folder is not touched) and writes one archive and one manifest:
bunx bizzpocket package [--dir .] [--out <file.tgz>] [--json] [--strict] [--skip-check]The archive is <theme id>-<version>.tgz (or --out), the manifest sits next to it as <name>.manifest.json and
inside the archive as package/bizzpocket.manifest.json. The command prints the size table, the content hash and the
sha512 of the archive. --json prints the manifest and the hashes as JSON.
What ships: the build as dist/, plus layouts/, locales/, assets/, public/, package.json, README,
CHANGELOG and LICENSE. Never shipped: source (blocks/, src/, theme.config.ts), node_modules, .git, tests,
source maps and root-level dotfiles.
Reproducible. The same source gives a byte-identical archive: sorted entries, mtime fixed at 1985-10-26 (npm's),
uid and gid 0, mode 0644, no user or host names, gzip level 9 with no name and no time. Two runs print the same
sha512. (A different zlib build can compress differently; the content hash below does not depend on it.)
Manifest. manifestVersion, id, name, version, sdk (cli, theme, themeRuntime, themeSdk, catalog), blocks
(type, variant, data mode), layouts, locales, files (path, size, sha256), contentHash (sha256: over the
sorted file list) and sizes (file count, unpacked bytes, client and CSS gzip, per block). A registry or store can
verify every file against it.
Safety. The command stops, and names the file, when the package would hold: a file named .env*, *.pem, *.key,
.npmrc, id_rsa* and the like; an absolute path of your machine; or in any shipped file a credential it recognises:
a bpdt_ developer token, BIZZPOCKET_DEV_TOKEN=, a PEM block of any kind (-----BEGIN ...-----), an _authToken,
an AWS key id, a Stripe sk_live_ / rk_live_ key, a GitHub ghp_ / gho_ / github_pat_ token, a Slack xox?-
token, a Google AIza... key, a JSON Web Token, a Razorpay rzp_live_ key or RAZORPAY_KEY_SECRET, and an
upper-case NAME_SECRET=, NAME_TOKEN= or NAME_KEY= assignment (also : in JSON) with a random-looking value
(names with PUBLIC or PUBLISHABLE are skipped). Every symlink in a shipped folder is refused, because the
target could be a secret (public/config.txt -> ../.env.local): copy the real file in. Dotfiles and dot-folders in
shipped folders are left out, except public/.well-known/. package.json ships as a minimal copy: name,
version, description, license, the bizzpocket field and the versions of @bizzpocket/* dependencies; never
scripts, publishConfig, repository or any other field that can hold a registry URL or a token.
The content scan is a safety net, not a guarantee. It finds known formats and obvious assignments. A token that is
split into pieces, encoded (base64, hex, reversed) or built at run time cannot be caught, and neither can a secret
in a format it does not know. Keep secrets out of the theme folder; do not rely on package to find them.
Gate. It runs bizzpocket check first and stops on an error (--strict: on a warning too). --skip-check skips
it and prints a warning.
Limits. 10 MB archive, 30 MB unpacked, 5 MB per file, 1500 files. The message names the limit, the size and the biggest files.
Publish: publish
0.3.0. Validates a package and says where it would go. It does not upload yet: the backend has no theme upload endpoint and no publisher token.
bunx bizzpocket publish [--dir . | --package <file.tgz>] [--store <slug> [--api <base>] | --registry <url>] [--dry-run]
[--strict] [--skip-check] [--trust-registry <host>]... [--allow-proxy]--dry-run verifies the archive against its manifest (or packages the theme first), resolves the target and prints the
package, the target, whether BIZZPOCKET_DEV_TOKEN would be sent, and the three requests of the proposed upload
(packages/cli/src/package/upload-contract.ts). Nothing is sent. The token goes only to the built-in hosts
(npm.bizzpocket.com, api.dev.bizzpocket.com) and --trust-registry hosts, over https, never while HTTP(S)_PROXY,
NODE_TLS_REJECT_UNAUTHORIZED (unless --allow-proxy) or a CA variable is set, and it is never printed.
Without --dry-run the command exits 1 and points to what works today: put the package on the registry
(bun publish) and submit it in the seller dashboard (see publishing), or, for a theme that lives
in this workspace, add it to the workspace so apps/storefront-v2/scripts/gen-theme-registry.mjs lists it.
The registry token that may publish and the verified publisher profile that may submit are both set up by the
BizzPocket team on request today (publishing).
Migrate a 2.x theme: migrate
migrate rewrites a theme written for SDK 2 (defineBlock, zod schemas, manifest.ts) into the SDK 3
layout. Always look first:
bunx bizzpocket migrate path/to/theme --dry-runmigrated 26 blocks: 12 converted, 7 review, 7 broken
files: 38 -> 37
ceremonyLines: 990 -> 31
registrations: 208 -> 0
blocks/cart/cart.tsx (broken):
- [info] contract.onSchemaError dropped (was 'degrade')
- [behaviour] CartFoodLineSchema: lineId: min length 1 dropped
- [blocking] <Client> kept inline (line 360: ...); it throws on the Next host (and `bizzpocket build` fails CLIENT_HOOK_IN_SERVER) until moved into a 'use client' file by hand
...
note: __tests__/manifest.test.ts: imports ../src/index, which migrate deleted(Output shortened.) --dry-run writes nothing. Each block ends converted (nothing to do), review (a
[behaviour] TODO: check it) or broken (a [blocking] TODO: fix it before it builds). Commit your work,
then run it for real, without --dry-run. --json prints the full report as JSON.
What migrate changes, every TODO and what to do after: migrate.md.
Type your blocks, layouts and messages: typegen
bizzpocket typegen [--dir <theme>] [--out <file.d.ts>] [--check]Writes three files from the theme, in types/ (or beside --out):
bizzpocket.d.ts:BlockProps<'hero'>(what the block'sfieldsgiverender, withf.font()asFontValue,f.range()asnumber, optional and defaulted fields as the SDK reads them),BlockData<...>(whatdata()resolves to),BlockRenderProps<...>,LayoutNode(a layout block node, typed by block), andMessageKey/ThemeTranslator(every key in your default locale file and the kit keys, each with its placeholders as required vars). The block types are not copied: the file reads your block modules with the SDK's ownPropsOfandDataOf.bizzpocket.register.d.ts: the registration, in its own file:declare module '@bizzpocket/theme' { interface Register { messages: Messages } }.layout.schema.json: JSON Schema forlayouts/*.json. A wrong block type,variantIdor prop, and a child a container does not allow, is marked in the editor. Map it in.vscode/settings.json:{ "json.schemas": [{ "fileMatch": ["layouts/*.json"], "url": "./types/layout.schema.json" }] }.
Include the theme's types/ folder in its tsconfig.json ("include": [..., "types"]). That is all: the register file
sets up your messages with the SDK, so ctx.t('cart.titel'), a missing placeholder, an extra one, or a plural key
without count is a compile error with no cast. Without the files (or before the first run) ctx.t accepts any key
and vars, as before. ThemeTranslator is still exported, but ctx.t as ThemeTranslator is no longer needed.
One theme per TypeScript program. Two themes' register files in one program clash on the same Register
interface (error TS2717, or the first theme silently wins under skipLibCheck). A theme's tsconfig.json must include
only its own types/ folder, never another theme's or a parent folder that holds several. In this monorepo every
theme has its own tsconfig.json, so this holds as long as none of them includes ../*/types.
With --out <dir>/<name>.d.ts the other names follow the .d.ts name: <name>.register.d.ts and
<name>.layout.schema.json (bizzpocket.d.ts keeps the plain layout.schema.json), so two themes can write into one
folder without overwriting each other. Paths are printed relative to the current folder when that is shorter.
The files are the same on every run (no dates, no absolute paths). --check writes nothing and exits 1 when any of the three files is
missing or differs from what a run would write, so CI can fail a stale file. The command reads your blocks the way
build does, so a block build rejects stops here with the same error.
Getting help
bunx bizzpocket --help # every command, one line each
bunx bizzpocket build --help # one command
bunx bizzpocket help build # the sameusage: bizzpocket build [--target next|bun|both] [--dir .] [--json]
Build dist/ and print the size report (server bytes, client JS, CSS, data mode per block, and why a block is runtime, with file:line).
--json prints the report as JSON instead.A wrong or missing argument prints the usage and exits with code 1. So does every failed command,
which makes the CLI safe to use in scripts and CI.
The CLI has no command that sends a theme to a store yet. To ship a theme, see publishing.md.
Next: publishing.md.