BizzPocket

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 edit

bunx @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:

ts
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 is block({ ... }) (blocks.md). If there is no <name>.tsx, the build uses the only .tsx file in the folder that is not 'use client'; with several, it stops with AMBIGUOUS_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:

tsconfig.json
{
  "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     216

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