BizzPocket

Introduction

On this page

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 calls block({ ... }). The block says what the seller can edit (its fields), 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.json holds the header and footer that every page shows. See layouts.md.
  • The theme config. theme.config.ts holds 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 any

Step by step:

  1. Route. The storefront turns the URL into a page type (product) and the values a block can read from page.route: the handle, q, page, sort and filters. The full URL table is in layouts.md.
  2. 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.
  3. 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).
  4. Data. Your data() functions did not run here. At build time each simple data() 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.
  5. Streaming. The answer is NDJSON (one JSON object per line). Line 1 holds the page, the layouts and the data of the critical blocks (lcp and aboveFold). Each later line is one finished need. The last line says the page is done.
  6. HTML. The storefront calls each block's render with 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.
  7. The browser gets complete HTML. Most blocks are now done: they are plain HTML and CSS.
  8. Interactivity, only where you asked for it: an island (a 'use client' file) becomes interactive ("hydrates"), and elements with sir.* 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 (an if, a ternary...);
  • a load() block, whose async load() 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: true and blocks visible without scrolling aboveFold: 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     147

Here 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