BizzPocket

Changelog

On this page

What changed in each Theme SDK release, for theme developers. The full, per-package changelogs are in the repository: packages/{theme,sir,theme-runtime,cli,blocks,theme-sdk}/CHANGELOG.md.

An SDK release is a set of package versions that work together:

SDK @bizzpocket/theme, sir, theme-runtime, cli @bizzpocket/blocks @bizzpocket/theme-sdk On npm.bizzpocket.com
3.0 0.1.0 0.3.0 2.22.0 Yes (2026-10-28)
3.1 + 3.2 0.2.0 0.4.0 2.23.0 No: first published inside 3.3
3.3 0.3.0 (theme, sir, theme-runtime, cli) 0.4.2 2.25.0 (@bizzpocket/fonts 0.1.0 is new) After the owner publishes (see Upgrading to 3.3)

Check what the registry has with:

bash
bun pm view @bizzpocket/cli version --registry https://npm.bizzpocket.com

Until 0.3.0 is published, the 3.1, 3.2 and 3.3 features below work only from a checkout of the BizzPocket repository (bun packages/cli/src/bin.ts <command>).

Contents: 3.3 · 3.2 · 3.1 · 3.0


SDK 3.3

3.3 makes pages fast by default and removes the code every theme had to copy. Released 2026-11-14 as @bizzpocket/theme 0.3.0, sir 0.3.0, theme-runtime 0.3.0, cli 0.3.0, theme-sdk 2.25.0 and fonts 0.1.0 (new).

Pages stay cached (@bizzpocket/theme-runtime)

  • A page is private only when it read shopper data. Before, one block with load() made the page private, no-store for every visitor with a cookie. Now catalogue and store operations (PUBLIC_OPS) are sent without the shopper's cookie, and only a customer* call makes the page private. limits.md
  • Keep no state between requests in load() and render(). A value kept in module scope can end up in another visitor's cached page. bizzpocket check flags it (theme/state-between-requests). data.md
  • A runtime data() that may read shopper data is always private: renamed helpers, aliases, member calls and gql() with a variable document all count. A runtime block that cannot be proved public loses page caching.
  • The runtime builds its browser bundle once per process. dev reloads no longer fail with "Bundle failed" on Bun 1.3.14.
  • page.route carries q, page and sort in render() on both hosts, not only in load(). routeQueryValues trims q and takes page as a whole number from 1.
  • Skip links work: the page's <main> is <main id="main-content" tabIndex={-1}>.
  • A failed or unknown query still gives null, and the host logs one theme.v3.query_failed line (op name and a short code, never variables or bodies).

New data needs

  • facets(), customer(), addresses(), orders(), order() and wishlist() resolve in the page's one round on both hosts. page() and pages() fetch REST needs without the cookie. A failed need marks the page degraded, so it is not cached.
  • f.product(), f.collection() and f.category() take fromRoute: true: the block gets the route's handle with no page.route.handle code in data().
  • menu({ handle, fallback }) takes a literal fallback handle.
  • The visibility.devices default ["mobile", "desktop"] no longer hides a block on tablets.

Less code to write (@bizzpocket/theme)

  • @bizzpocket/theme/browse: URL filter, sort and page helpers. Replaces the same imports from @bizzpocket/theme-sdk.
  • @bizzpocket/theme/kit: formatMoney, Price, JsonLd, Breadcrumbs, Pager, FilterRail, path helpers, variant options and colour swatches, unstyled. Options on JsonLd, Pager, FilterRail, the cart model and ProductCard (slots.actions) let a theme keep its existing HTML. Do not put a button, link or input in a ProductCard slot that renders inside the link (slots.media and slots.body in whole-card mode, the badge): use slots.actions. Development builds warn once.
  • JsonLd writes absolute URLs with no origin prop and skips an entry the page head already carries.
  • Customer auth in @bizzpocket/theme/client: useCustomerAuth() with sign-in, one-time code, sign-up, sign-out and password reset. Pass storeSlug from ctx.store.slug. No copied transport file and no raw fetch.
  • <Money> prints the same text on the server and in the browser (currency home locale by default).
  • Cart totals round half up through the decimal digits (USD 1.005 is 1.01).

Translations, fonts and head

  • Translations. A theme with locales/ gets one locale per page, <html lang dir>, and ctx.t, ctx.format and ctx.locale in every block. ctx.t.raw(key) and fillTemplate() hand a template to a client island. bizzpocket typegen types ctx.t keys and placeholders. Kit components print the page language in Bun, Next and React Server Components. Behaviour change: format.list without a translator joins in English; set kit.list.* in the locale file.
  • Fonts. theme({ fonts: { catalog: true } }) opts in to the self-hosted font catalog (@bizzpocket/fonts) for token fonts, Appearance choices and f.font() values. Off by default, and existing themes emit no new font CSS.
  • Head. A block's head() can return a translated title (HeadContext has t, format, dir). Canonical, Open Graph, Twitter and JSON-LD come from one resolved head. Filtered or sorted URLs are noindex, follow, and listing pages 2 and up get the storefront's "Page N" title and description.

Check and build a theme (@bizzpocket/cli)

  • bizzpocket check reports layout mistakes, blocks that leave the page's single data request, size budgets and lint gaps, with the file and a fix for each. --strict is for CI. New rule groups: i18n/*, seo/*, layout/unknown-font, layout/out-of-range, perf/font-budget, perf/renderer-need. cli.md
  • bizzpocket build --out <folder> writes everything to that folder. The output folder is marked, and a rebuild deletes only what the last build wrote.
  • locales/<locale>.json is validated at build (INVALID_LOCALE).
  • dev --locale <tag>, dev --mock answers the new needs, and --mock-guest returns null for shopper data.
  • bizzpocket css-split (opt-in, css: { split: true }) moves global CSS rules into the blocks' own files.
  • Phone media queries work on Chrome < 104 (older Android).
  • A block is no longer wrongly called runtime for common export shapes. A block module with two block exports fails the build (NOT_A_BLOCK).
  • The blank starter lints blocks/ and passes check --strict.

Removed

  • @bizzpocket/theme-sdk ./controllers: the unused checkout controller stub. Checkout is the host's page.

For contributors

  • bun run theme:setup prepares a fresh checkout for theme work. contributing.md

SDK 3.2

3.2 makes the SDK usable by developers outside BizzPocket: a store's own developer token, the whoami command, this documentation site, and the open bugs closed.

Developer tokens and whoami (@bizzpocket/cli 0.2.0)

  • dev --store takes a per-store developer token. A store owner makes one in the seller dashboard under Settings → Developers. It starts with bpdt_, reads only that store's public storefront data, expires, and can be revoked. Put it in BIZZPOCKET_DEV_TOKEN in your shell. The CLI sends it only to the --api host, in the x-bp-dev-token header. The team's internal token still works as before. tokens.md
  • bizzpocket whoami --store <slug> checks the token before you start: its store and expiry, or why it does not work (revoked, expired, for another store). cli.md

Fixes (next release)

  • dev and the Bun bundle no longer need @bizzpocket/theme-sdk or zod installed (cli). Before, a theme outside the repository with no theme-sdk got HTTP 500 on every page (Cannot find module '@bizzpocket/theme-sdk/v3').
  • dev --prod works after a plain dev run (cli). It used to fail every page with jsxDEV_… is not a function. cli.md
  • No double download of the LCP image (theme, theme-sdk, sir). With a srcset, <Image> and responsiveImage() now set a mid-size src (the widest candidate up to 960w), never the full-size master. The SIR variant picker keeps the server's srcset on the opening picture instead of dropping it. Nothing to change in your code. data.md
  • A failed block never shows its error as page text (theme-sdk). It renders an empty hidden marker. The error kind goes to the log and, in development and preview only, to data-bp-error.
  • Cart line errors reach your island (sir). A failed cart:update or cart:remove now sends bizzpocket:cart:error with the lineId, so useCartActions().update() and .remove() reject with the store's error code instead of timing out after 15 s. interactivity.md
  • The carousel behaviour disables prev/next at the ends of the track (disabled and aria-disabled="true").
  • An empty [data-bp-carousel-dots] inside a carousel is filled with one dot per slide. The visible slide's dot has aria-current="true".
  • The registry's testimonials block has its dot pager back. Re-copy it with bizzpocket add testimonials --overwrite if you have not changed it (registry.md).

interactivity.md


SDK 3.1

Shopper state in islands (@bizzpocket/theme/client 0.2.0)

Four new hooks. An island pays only for the ones it imports (all four together are 2.7 KB gz).

  • useCartActions(): add, update, remove as Promises, with pending and error. interactivity.md
  • useShared(key, initial): one value shared by every island on the page, and by SIR behaviours. state.md
  • useQuery(op, vars): public catalogue data from the browser, through GET /_bp/q/<op>, with a per-tab cache. data.md
  • useForm(submit, { validate }): native validation, then yours, then submit; no double submit. interactivity.md

Variant picker without React (@bizzpocket/sir, @bizzpocket/theme 0.2.0)

  • A new SIR variant-picker behaviour picks a product variant with no JavaScript of your own: it updates the price, SKU, stock, image, add-to-cart button and ?variant=. It is keyboard-accessible.
  • Write its markup with sir.variantPicker, sir.variantGroup, sir.variantOption, sir.variantData, sir.variantTarget and sir.variantImage. sir.variantState gives the opening state, so nothing flashes on load.
  • The SIR boot script grows from 3.74 to 5.92 KB gz.

interactivity.md

Images

  • <Image> adds srcset and sizes by itself for BizzPocket CDN and Unsplash images. New props widths (the candidates) and srcSet (yours, or '' to turn it off). Existing calls need no change. data.md

Container blocks

  • f.blocks() makes a block a container: it receives its child blocks, already rendered, and places them in its own markup. Children stream in on their own. Up to 3 levels deep, 24 children by default. group.md
  • The registry has a group block (@bizzpocket/blocks 0.4.0): a CSS-only row, column or grid for other blocks. bizzpocket add group. group.md
  • add-to-layout --parent <id> puts a block inside a container. cli.md

New field options (@bizzpocket/theme 0.2.0)

  • f.collections(): a list of collections, like f.categories().
  • f.number({ integer: true }): whole numbers only; a saved fraction is cut off.
  • f.video({ format: 'url' }): the video as a plain URL string.
  • f.list({ hidden, optional }), and optional on f.products(), f.categories() and f.collections().
  • An optional field with a default now starts new blocks with that default, while a saved block without the key still reads undefined.
  • In a field map where some fields set tier, the fields without one are advanced.

fields.md

Build tells you why a block is runtime (@bizzpocket/cli 0.2.0)

  • Under the size table, one line per runtime block: file, line, what is in the way, and a reason code, for example blocks/x/x.tsx:14 ternary (?:) in data() [data-not-static]. data.md
  • size-report.json carries at, reason and detail for every runtime block. New reason field-kind.
  • build --json prints the report as JSON. cli.md

Migrate keeps more (@bizzpocket/cli 0.2.0)

migrate now keeps .int(), a list's hidden hint, 2.x optional props (as optional plus default), video-URL strings and collection pickers. It skips the 2.x islands-codemod output (.bizzpocket/). migrate.md

Fixes

  • The theme's own design tokens are written as the base :root CSS variables (theme-runtime).
  • The packages install outside the BizzPocket repository: no private @repo/* dependency is left in their manifests.

SDK 3.0

The first release of the new way to write themes. Themes written for SDK 2 keep working.

  • @bizzpocket/theme: block(), f.* fields, theme(), the data helpers (products(), product() and the rest), load(), Image, Link, Money, and 'use client' islands with useCart. first-block.md
  • One block is one folder. The folder name is the block's name. There is nothing to register.
  • Static data. A data() made of plain helper calls becomes a template at build time, and the whole page's data is fetched in one call. data.md
  • @bizzpocket/cli: init, dev (--mock and --store), build with the size report, add, diff, add-to-layout and migrate. cli.md
  • @bizzpocket/blocks 0.3.0: the registry of blocks and components you copy into your theme. responsiveImage, isSafeUrl, isSafeMediaUrl and toSafeUrl are @bizzpocket/theme exports, not copied components. registry.md
  • @bizzpocket/theme-sdk 2.21–2.22: the ./v3 adapter, which lets the current storefront host render SDK 3 blocks unchanged. A theme built by the CLI is marked builder: 'bizzpocket-cli'.
  • Upgrade note (theme-sdk 2.22). LoadContext.query is typed by the known operation names. A theme migrated before 2.22 keeps an old legacy-loader-context.ts that fails tsc (the build still works). Run bizzpocket migrate again, or cast ctx.query(op as OpName, vars) in that file.