Changelog
On this page
- SDK 3.3
- Pages stay cached (@bizzpocket/theme-runtime)
- New data needs
- Less code to write (@bizzpocket/theme)
- Translations, fonts and head
- Check and build a theme (@bizzpocket/cli)
- Removed
- For contributors
- SDK 3.2
- Developer tokens and whoami (@bizzpocket/cli 0.2.0)
- Fixes (next release)
- Carousel (@bizzpocket/sir, @bizzpocket/blocks, next release)
- SDK 3.1
- Shopper state in islands (@bizzpocket/theme/client 0.2.0)
- Variant picker without React (@bizzpocket/sir, @bizzpocket/theme 0.2.0)
- Images
- Container blocks
- New field options (@bizzpocket/theme 0.2.0)
- Build tells you why a block is runtime (@bizzpocket/cli 0.2.0)
- Migrate keeps more (@bizzpocket/cli 0.2.0)
- Fixes
- SDK 3.0
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:
bun pm view @bizzpocket/cli version --registry https://npm.bizzpocket.comUntil 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 pageprivate, no-storefor every visitor with a cookie. Now catalogue and store operations (PUBLIC_OPS) are sent without the shopper's cookie, and only acustomer*call makes the page private. limits.md - Keep no state between requests in
load()andrender(). A value kept in module scope can end up in another visitor's cached page.bizzpocket checkflags it (theme/state-between-requests). data.md - A runtime
data()that may read shopper data is alwaysprivate: renamed helpers, aliases, member calls andgql()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.
devreloads no longer fail with "Bundle failed" on Bun 1.3.14. page.routecarriesq,pageandsortinrender()on both hosts, not only inload().routeQueryValuestrimsqand takespageas 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 onetheme.v3.query_failedline (op name and a short code, never variables or bodies).
New data needs
facets(),customer(),addresses(),orders(),order()andwishlist()resolve in the page's one round on both hosts.page()andpages()fetch REST needs without the cookie. A failed need marks the page degraded, so it is not cached.f.product(),f.collection()andf.category()takefromRoute: true: the block gets the route's handle with nopage.route.handlecode indata().menu({ handle, fallback })takes a literal fallback handle.- The
visibility.devicesdefault["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 onJsonLd,Pager,FilterRail, the cart model andProductCard(slots.actions) let a theme keep its existing HTML. Do not put a button, link or input in aProductCardslot that renders inside the link (slots.mediaandslots.bodyinwhole-cardmode, the badge): useslots.actions. Development builds warn once.JsonLdwrites absolute URLs with nooriginprop 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. PassstoreSlugfromctx.store.slug. No copied transport file and no rawfetch. <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>, andctx.t,ctx.formatandctx.localein every block.ctx.t.raw(key)andfillTemplate()hand a template to a client island.bizzpocket typegentypesctx.tkeys and placeholders. Kit components print the page language in Bun, Next and React Server Components. Behaviour change:format.listwithout a translator joins in English; setkit.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 andf.font()values. Off by default, and existing themes emit no new font CSS. - Head. A block's
head()can return a translated title (HeadContexthast,format,dir). Canonical, Open Graph, Twitter and JSON-LD come from one resolved head. Filtered or sorted URLs arenoindex, follow, and listing pages 2 and up get the storefront's "Page N" title and description.
Check and build a theme (@bizzpocket/cli)
bizzpocket checkreports layout mistakes, blocks that leave the page's single data request, size budgets and lint gaps, with the file and a fix for each.--strictis for CI. New rule groups:i18n/*,seo/*,layout/unknown-font,layout/out-of-range,perf/font-budget,perf/renderer-need. cli.mdbizzpocket 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>.jsonis validated at build (INVALID_LOCALE).dev --locale <tag>,dev --mockanswers the new needs, and--mock-guestreturnsnullfor 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
runtimefor common export shapes. A block module with two block exports fails the build (NOT_A_BLOCK). - The blank starter lints
blocks/and passescheck --strict.
Removed
@bizzpocket/theme-sdk./controllers: the unused checkout controller stub. Checkout is the host's page.
For contributors
bun run theme:setupprepares 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 --storetakes a per-store developer token. A store owner makes one in the seller dashboard under Settings → Developers. It starts withbpdt_, reads only that store's public storefront data, expires, and can be revoked. Put it inBIZZPOCKET_DEV_TOKENin your shell. The CLI sends it only to the--apihost, in thex-bp-dev-tokenheader. The team's internal token still works as before. tokens.mdbizzpocket 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)
devand the Bun bundle no longer need@bizzpocket/theme-sdkor 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 --prodworks after a plaindevrun (cli). It used to fail every page withjsxDEV_… is not a function. cli.md- No double download of the LCP image (
theme,theme-sdk,sir). With asrcset,<Image>andresponsiveImage()now set a mid-sizesrc(the widest candidate up to 960w), never the full-size master. The SIR variant picker keeps the server'ssrcseton 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, todata-bp-error. - Cart line errors reach your island (
sir). A failedcart:updateorcart:removenow sendsbizzpocket:cart:errorwith thelineId, souseCartActions().update()and.remove()reject with the store's error code instead of timing out after 15 s. interactivity.md
Carousel (@bizzpocket/sir, @bizzpocket/blocks, next release)
- The
carouselbehaviour disables prev/next at the ends of the track (disabledandaria-disabled="true"). - An empty
[data-bp-carousel-dots]inside a carousel is filled with one dot per slide. The visible slide's dot hasaria-current="true". - The registry's
testimonialsblock has its dot pager back. Re-copy it withbizzpocket add testimonials --overwriteif you have not changed it (registry.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,removeas Promises, withpendinganderror. interactivity.mduseShared(key, initial): one value shared by every island on the page, and by SIR behaviours. state.mduseQuery(op, vars): public catalogue data from the browser, throughGET /_bp/q/<op>, with a per-tab cache. data.mduseForm(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-pickerbehaviour 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.variantTargetandsir.variantImage.sir.variantStategives the opening state, so nothing flashes on load. - The SIR boot script grows from 3.74 to 5.92 KB gz.
Images
<Image>addssrcsetandsizesby itself for BizzPocket CDN and Unsplash images. New propswidths(the candidates) andsrcSet(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
groupblock (@bizzpocket/blocks0.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, likef.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 }), andoptionalonf.products(),f.categories()andf.collections().- An
optionalfield with adefaultnow starts new blocks with that default, while a saved block without the key still readsundefined. - In a field map where some fields set
tier, the fields without one areadvanced.
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.jsoncarriesat,reasonanddetailfor every runtime block. New reasonfield-kind.build --jsonprints 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
:rootCSS 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 withuseCart. 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(--mockand--store),buildwith the size report,add,diff,add-to-layoutandmigrate. cli.md@bizzpocket/blocks0.3.0: the registry of blocks and components you copy into your theme.responsiveImage,isSafeUrl,isSafeMediaUrlandtoSafeUrlare@bizzpocket/themeexports, not copied components. registry.md@bizzpocket/theme-sdk2.21–2.22: the./v3adapter, which lets the current storefront host render SDK 3 blocks unchanged. A theme built by the CLI is markedbuilder: 'bizzpocket-cli'.- Upgrade note (theme-sdk 2.22).
LoadContext.queryis typed by the known operation names. A theme migrated before 2.22 keeps an oldlegacy-loader-context.tsthat failstsc(the build still works). Runbizzpocket migrateagain, or castctx.query(op as OpName, vars)in that file.