Project structure
On this page
A theme is one folder. The build finds everything in it by name: there is no registration file, no
index.ts and no manifest.ts. This page lists every file and folder, what the build writes to dist/,
and the naming rules.
my-theme/
theme.config.ts id, name, tokens, styles, starter content
package.json name, version, the "./styles" export
tsconfig.json optional: type checking in your editor and with tsc
bizzpocket.json written by `bizzpocket add`: what you copied from the registry
blocks/
featured-collection/
featured-collection.tsx the block: export default block({ ... })
featured-collection.css its CSS (imported by the .tsx)
heart.tsx 'use client': an island of this block
format.ts any other helper file
components/
money-price/
money-price.tsx shared pieces, used by several blocks
layouts/
global.json header and footer, on every page
home.json one file per page type
product.json
styles/
global.css optional: CSS for every page
dist/ written by `bizzpocket build`; do not editbunx @bizzpocket/cli init my-theme creates a small working store: theme.config.ts, package.json, README.md,
eleven blocks in blocks/, a layout for nine pages, locales/en.json and locales/hi.json, styles/global.css and a
generated types/ folder. That theme builds and passes bizzpocket check --strict. cli.md
lists the files.
The files you write
theme.config.ts
The theme's settings. The default export is theme({ ... }) from @bizzpocket/theme:
import { theme } from '@bizzpocket/theme';
export default theme({
id: 'my-theme',
name: 'My Theme',
tokens: {
colors: { primary: '#111111', background: '#ffffff' },
fonts: { body: 'system-ui' },
},
});id must be a string literal: the build reads it without running the file. Every option (tokens,
styles, verticals, starter content...): theme-config.md. .tsx, .mts, .js and
.mjs also work; without any, the build stops with NO_CONFIG.
package.json
| Key | Why |
|---|---|
name |
Required. init writes @bizzpocket/theme-<id> (@bizzpocket/theme-my-theme), the only name the marketplace accepts; the build takes any npm name. If theme.config.ts has no id, the id is the name without its scope. |
version |
Required. A semantic version (0.1.0). It is the theme's version: the build stamps it on every layout. |
exports["./styles"] |
Must be "./dist/styles.css", or the build stops with STYLES_EXPORT_MISSING. |
type |
"module". |
devDependencies |
@bizzpocket/cli and @bizzpocket/theme. |
peerDependencies |
react and react-dom 19, and @bizzpocket/theme-sdk (the storefront provides them). |
Any npm package you bun add can be used in blocks and islands; it is bundled into the build.
blocks/<name>/
One folder per block. The folder name is the block's type: layouts and saved store pages refer to the block by it.
- The block file is
blocks/<name>/<name>.tsx. Its default export isblock({ ... })(blocks.md). If there is no<name>.tsx, the build uses the only.tsxfile in the folder that is not'use client'; with several, it stops withAMBIGUOUS_BLOCK_FILE. - Islands are files whose first line is
'use client'. They are the only code sent to the browser (interactivity.md). - CSS files are imported by the block file (
import './<name>.css'). They load only on pages that use the block. - Anything else (helpers, sub-components, types) can live in the folder too. Only the block file is the block.
components/
Code shared by several blocks: a price label, a product card. bizzpocket add <component> copies registry
components to components/<name>/. Your own can go anywhere in the theme; import them with relative paths
(../../components/money-price/money-price). A 'use client' file in components/ becomes an island of
the first block (in folder order) that imports it.
bizzpocket add can also write data/<name>.ts (data helpers) and traits/<name>.ts (trait fields)
(registry.md).
layouts/*.json
The default blocks of each page. The file name is the page type (home.json, product.json,
cart.json...) or global for the header and footer. Any other name stops the build. The page types,
their URLs and the JSON: layouts.md.
styles/global.css
Optional CSS loaded on every page, before the blocks' CSS. Keep it small: resets, fonts, layout helpers.
bizzpocket.json
Written by bizzpocket add. It records each item you copied from the registry, its version and a hash of
each file, so bizzpocket diff can show what changed upstream and add does not overwrite your edits.
Commit it. Do not edit it by hand (registry.md).
tsconfig.json
Optional. The build does not need it (it bundles with Bun), but it lets your editor and tsc check the
block types:
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"lib": ["ES2022", "DOM"]
},
"include": ["blocks", "components", "theme.config.ts"]
}Then bun add -d typescript @types/react and bunx tsc -p .
(first-block.md).
Other files
The build ignores everything else: README.md, CHANGELOG.md, tests, locales/, src/. Use them as you
like. bizzpocket dev watches blocks/, layouts/, components/ and theme.config.ts; after a change
anywhere else, restart it.
What bizzpocket build writes: dist/
Everything the build makes goes to dist/. Your source files are never rewritten. A failed build puts the
previous dist/ back. Add dist/ to .gitignore.
dist/
blocks.json the editor catalogue
templates.json data templates and default layouts, for the page call
size-report.json the size table, as JSON
index.js server bundle for the Next.js storefront (--target next)
index.d.ts its types (--target next)
styles.css all CSS: global first, then each block (--target next)
bun/ (--target bun)
server.js server bundle for the Bun renderer
assets.json island id -> client file, block -> CSS file
client/ one file per island, with a content hash in its name
css/ one file per block (<type>.css), plus global.css--target both (the default) writes both sets.
| File | What is in it | Who reads it |
|---|---|---|
blocks.json |
Every block: type, displayName (your name), description, category, role, container, propsSchema (your fields as JSON Schema with editor hints, plus x-bp-data, the data template) and defaultProps. Also your default layouts, the global layout, token names, styles and starter content. |
The seller's page editor. |
templates.json |
A hash, each block's data template keyed "<type>|<variant>" (static with its needs, or runtime), the componentMapping, the default layouts (with @global) and starter content. |
The page call: the API fills these templates with saved props. |
size-report.json |
Per block: type, serverBytes, clientGzipBytes, cssGzipBytes, data (static, runtime or none) and, for a runtime block, reason, detail and at (file and line). Then totalClientGzip and totalCssGzip. build --json prints it. |
You, and CI. |
index.js, index.d.ts, styles.css |
The theme as the Next.js storefront loads it. | The Next.js storefront. |
bun/* |
The theme as the Bun renderer loads it. | bizzpocket dev, @bizzpocket/theme-runtime. |
The build also prints the size table:
block server B client gz css gz data
------------------- -------- --------- ------ ------
featured-collection 1490 0 213 static
hello 292 0 0 none
total 0 216server B is the block's server code in bytes, client gz its islands (gzip bytes), css gz its CSS
(gzip bytes). How to read data: data.md.
Naming rules
| What | Rule | Example | If not |
|---|---|---|---|
| Theme id | lowercase letters, digits and dashes, starting with a letter | my-theme |
INVALID_THEME_ID |
init folder |
becomes the theme id, so the same rule | bunx @bizzpocket/cli init my-theme |
INVALID_THEME_ID |
| Block folder | the same rule | blocks/product-grid/ |
INVALID_BLOCK_NAME |
| Two block folders | must differ after dashes are removed | not hero-2 and hero2 |
DUPLICATE_BLOCK_IDENT |
| Block file | <folder>.tsx |
blocks/product-grid/product-grid.tsx |
NO_BLOCK_FILE, AMBIGUOUS_BLOCK_FILE |
| Island file name | unique in its block, extension aside | not heart.ts and heart.tsx |
DUPLICATE_ISLAND |
| Layout file | a page type, or global |
layouts/order_detail.json |
INVALID_MANIFEST |
| CSS classes | a prefix unique to the block (all blocks share the page) | .fc-grid |
styles clash |
| Field keys | not the name of a data helper (product, products, menu, store...) |
productHandle |
the block goes runtime |
Page types use underscores (order_detail.json, not_found.json); block folders use dashes.
Warning. Once a store uses your theme, do not rename a block folder or a field key. Saved layouts refer to them by name, and the section or value silently disappears (layouts.md).
Next: blocks.md.