Introduction
A BizzPocket theme is a folder of React blocks and JSON layouts that decides how a store looks. This page explains what a theme is, how a page is built from it, which packages do what, and why a theme sends no JavaScript to the browser unless you ask for it.
You need to know React. You do not need to know anything about BizzPocket yet.
What a theme is
A theme has three parts:
- Blocks. A block is one section of a page: a header, a hero picture, a product grid. Each block is
one folder in
blocks/, with one file that callsblock({ ... }). The block says what the seller can edit (itsfields), what data it needs (data()), and how it looks (render). See blocks.md. - Layouts. A layout is a JSON file in
layouts/that lists the blocks of one page, in order:home.json,product.json,cart.json...global.jsonholds the header and footer that every page shows. See layouts.md. - The theme config.
theme.config.tsholds the theme's id, name, colours and fonts. See theme-config.md.
Your layouts are only the starting point. In the seller dashboard, the seller adds, removes, reorders and edits blocks. Their saved layout then replaces your default for their store. Your blocks are the pieces they build with.
A file tree with every file explained is in project-structure.md.
How a page is rendered
When a shopper opens /products/wooden-train, this happens:
Shopper's browser Storefront server BizzPocket API (Rust)
───────────────── ───────────────── ─────────────────────
GET /products/wooden-train ──▶ 1. URL -> page type "product",
handle "wooden-train"
2. one page call ─────────────────▶ 3. picks the layout:
(store, page type, route, the seller's saved one,
your data templates) else your layouts/product.json
4. collects the needs of every
block in it and in global.json,
runs them together
5. ◀──────────── NDJSON stream ────── line 1: page + critical data
next lines: one per need
last line: { "done": true }
6. renders each block's `render`
to HTML, streams the page
7. ◀──────── HTML (no JS) ──────
8. islands / sir attributes
wake up, only if the page
has anyStep by step:
- Route. The storefront turns the URL into a page type (
product) and the values a block can read frompage.route: thehandle,q,page,sortand filters. The full URL table is in layouts.md. - One page call. The storefront makes one request to the BizzPocket API for the whole page. It sends
a hash of your theme's data templates (
dist/templates.json). When the API has not seen that hash yet, the storefront sends the whole file once. - Layout. The API picks the page's layout: the seller's saved layout for this page, else your default
from
layouts/. It does the same for the header and footer (global.json). - Data. Your
data()functions did not run here. At build time each simpledata()was turned into a template (a "static" block). The API fills each template with the block's saved props and the route, removes duplicates, and runs every need of the page at the same time. - Streaming. The answer is NDJSON (one JSON object per line). Line 1 holds the page, the layouts and
the data of the critical blocks (
lcpandaboveFold). Each later line is one finished need. The last line says the page is done. - HTML. The storefront calls each block's
renderwith its props and data, and streams the HTML. Critical blocks are in the first part. A block whose data is still on its way shows a placeholder and fills in when its line arrives. Blocks appear in page order, so nothing jumps. - The browser gets complete HTML. Most blocks are now done: they are plain HTML and CSS.
- Interactivity, only where you asked for it: an island (a
'use client'file) becomes interactive ("hydrates"), and elements withsir.*attributes (add to cart, carousel, accordion...) are wired up by a small shared runtime.
Two kinds of block take a slower path, with one extra round of fetches after the page call:
- a runtime block, whose
data()the build could not turn into a template (anif, a ternary...); - a
load()block, whose asyncload()runs on every request.
Both still work. The build's size report tells you which blocks they are and why (data.md).
If a block throws while rendering, only that block is empty. The rest of the page renders.
Note. BizzPocket has two storefront hosts. The Next.js storefront serves stores today and runs your
blocks through @bizzpocket/theme-sdk/v3; it uses the single page call when its page endpoint is
switched on, and otherwise fetches every block's needs itself, all at the same time. The Bun renderer,
@bizzpocket/theme-runtime, always works as described above. bizzpocket dev uses the Bun renderer,
so what you see locally is the path above.
The packages
| Package | What it is | Do you import it? |
|---|---|---|
@bizzpocket/theme |
The author API: block, f (fields), theme, the data helpers (products, product, menu...), Image, Link, Money and sir. @bizzpocket/theme/client has the hooks for islands (useCart, useCustomer, useQuery...). |
Yes. Every block file. |
@bizzpocket/cli |
The bizzpocket command: init, dev, whoami, build, add, diff, add-to-layout, migrate. It builds dist/ and prints the size report. |
No. You run it. |
@bizzpocket/blocks |
The registry: blocks, components, data helpers and traits you copy into your theme with bizzpocket add. Once copied, the code is yours. See registry.md. |
No. add copies from it. |
@bizzpocket/sir |
SIR, the Storefront Interaction Runtime: the small browser script behind sir.addToCart(), sir.carousel() and the other sir.* attributes. |
No. Use sir from @bizzpocket/theme. |
@bizzpocket/theme-runtime |
The Bun renderer: the page call, streamed HTML, islands, per-page CSS, brotli. bizzpocket dev runs it. |
No. |
@bizzpocket/theme-sdk |
The 2.x SDK and the host layer. The CLI checks your manifest and layouts with its schemas, and the Next.js storefront runs your blocks with @bizzpocket/theme-sdk/v3. |
No. Islands may not import it. Moving a 2.x theme: migrate.md. |
The performance model
By default, a block sends 0 KB of JavaScript. render runs on the server. The browser gets HTML and
CSS. On the Bun renderer, a page with no islands and no sir attributes loads no script file at all.
(When blocks stream in, React adds a few small inline scripts that put each one in its place.)
JavaScript is added only in these cases:
| You write | The browser loads |
|---|---|
A sir.* attribute ({...sir.addToCart({ 'data-product-id': p.id })}) |
The shared SIR runtime, once per page. Nothing from your theme. |
A 'use client' file that a block imports (an island) |
The island's own code (shown in the client gz column), the island loader and React. Only on pages that use the block. |
Each island wakes up when it comes near the screen, by default. Set hydrate: 'load' or 'idle' on the
block to change that (interactivity.md).
Other things that keep pages fast:
- One data call per page for static blocks, with identical needs fetched once.
- CSS per block. A block's CSS loads only on pages that use it.
- Critical blocks first. Mark the hero
lcp: trueand blocks visible without scrollingaboveFold: true; the page waits for their data before it sends the first part of the HTML. Its first picture is loaded eagerly with high priority. - Caching. A page without personal data is cached for a short time at the edge.
bunx bizzpocket build prints the cost of every block:
block server B client gz css gz data
---------------- -------- --------- ------ ------
announcement-bar 693 0 145 none
hero-banner 927 0 0 none
product-summary 799 0 0 static
size-guide 442 268 0 none
total 268 147Here only size-guide sends JavaScript (268 bytes gzip, one island), and product-summary gets its data
in the page call (static).
Where to go next
- Build a block in half an hour: first-block.md
- Every file in a theme: project-structure.md
- The
block()API: blocks.md - Page types, URLs and layout JSON: layouts.md
- Fields the seller edits: fields.md
- Data, static and runtime: data.md
- Islands, hooks and
sir: interactivity.md - Colours, fonts and styles: theme-config.md