Builder delivery modes
A store reads its Throttle Builder pages in one of two ways, chosen per store: live (the default) or build. In build mode the store generates every page from a frozen release when you build it and makes no Builder request while it runs.
Live and build
| Live (default) | Build | |
|---|---|---|
| When a change shows | Soon after you publish: the Builder sends a signed change notice and the store clears the cached pages. | When you press Release and the store has been built again from that release. |
| Builder reads | At request time, cached for at least an hour and cleared by a change notice. | Only while the store builds: one read of the release bundle. |
| Pages | Rendered on demand and kept; the number prerendered defaults to 0 and is capped at 50. | Every page of the release is generated at build, on purpose. |
| Cost on your host | ISR writes when a notice clears a page. | One full build per release, zero Builder-driven ISR writes. Catalog changes still re-render pages, as in live mode. |
| Client | createBuilderClient({ builderKey }) | createBuilderClient({ mode: 'build', builderKey }) |
Live mode is unchanged by build mode. In the Builder, a store's release settings say which mode it is in; switching to build mode gives up any change notices still waiting, because nothing reads them.
Releases, the Release button and the deploy hook
In build mode, published changes pile up. Release (in the Builder, or a secret key holding releases:write) freezes everything published at that moment into one immutable release: site settings, every page, the header and
footer, slots, the frozen custom widgets and the frozen assets. A release id never changes what it holds, and a rollback is a new release of an older
snapshot.
Set a deploy hook in the Builder's release settings (Vercel: Project Settings, Git, Deploy Hooks; Netlify and any https URL work too). Each release calls it once, with retries, and the host builds the store again. A store with no hook still releases; you start the build yourself.
The build client
import { createBuilderClient } from '@usethrottle/builder';
// Build mode: the Builder is read while `next build` runs, never while the store runs.
const builder = createBuilderClient({
mode: 'build',
builderKey: process.env.THROTTLE_BUILDER_KEY!, // tb_pk_... of a server channel, or a tb_sk_... key with releases:read
});
const bundle = await builder.getReleaseBundle(); // BUILDER_RELEASE_ID, else the newest release
const page = await builder.pages.get('about'); // answered from the bundle: no request getReleaseBundle({ release? }) reads GET /v1/releases/latest/bundle or GET /v1/releases/:id/bundle, once per process. The release is the argument, else the client's release option, else the BUILDER_RELEASE_ID environment variable, else the newest. A value that is
not a 26-character release id fails with a message naming it, before any request. The client sends no cache tags, runs no generation watcher and listens for no
notices. Every other read of the client (site, pages, parts, slots, bundle) is answered from the bundle, so @usethrottle/builder-react renders
it with no network.
| Key | Use |
|---|---|
tb_pk_... | The publishable key of a server channel is the build key. Sent as X-Builder-Key, never with an Origin. |
tb_sk_... | A secret key holding releases:read. Sent as a bearer token. |
THROTTLE_BUILDER_KEY in your server and build environment only, never in a NEXT_PUBLIC_ variable.
The browser needs no Builder key in build mode.
A bundle is read into memory whole, up to 48 MB, so the build machine needs that headroom. A response that is cut short fails with "bundle truncated (too large or interrupted)".
A build that cannot read its release (a wrong id, a site with no release yet, a refused key, Builder down) fails the build with a clear error. It never bakes a store without its header and footer into every page, which is what a live store does to ride out an outage.
The announcement bar
A release holds the announcement with its on/off switch and its startsAt and endsAt. The window is decided when a page is
rendered, not when the release is made, because build-time sites get no change notices. The Builder pages of a build-mode store are generated once, at build, so on them a
start or end time that passes after the build only takes effect with the next release. The bar also shows on pages rendered per request (the catalog pages: shop, search,
products), and on those it turns on and off at its times with no rebuild.
Next.js
// app/pages/[handle]/page.tsx
import { createBuilderPage } from '@usethrottle/builder-react/next';
import { builderStaticParams } from '@usethrottle/builder-react/server';
import { builder } from '@/lib/builder';
export const generateStaticParams = () => builderStaticParams({ client: builder });
export const dynamicParams = false;
const route = createBuilderPage({ fromParams: 'handle', client: builder /* , packs, slots, locale */ });
export default route.Page;
export const generateMetadata = route.generateMetadata; builderStaticParams lists every page of the release and refuses a live client. Build mode is the one place a store generates every
page: a release is one build, not one write per visit. create-store sets all of this up:
npx @usethrottle/create-store my-store --builder-mode build THROTTLE_BUILDER_KEY=tb_pk_... # build key: the publishable key of a server channel. Server and build only.
THROTTLE_MEDIA_ORIGIN=https://... # the origin your Builder images are served from
BUILDER_RELEASE_ID= # optional: build this release instead of the newest
The scaffold reads the newest release (or BUILDER_RELEASE_ID) once, in next.config.ts, and writes it to .builder/release.json. Next copies that file into the build output (outputFileTracingIncludes), and every page, the
layout's header, footer and slots, and the sitemap render from it. The running store makes no Builder request at all, not even on a cold instance rendering search or a
product page, and needs no Builder key. If the file is missing or corrupt at run time the page fails with a clear error, even when the key is set on the host: a
quiet fallback would download the whole release on every cold start. Only next dev reads from the Builder (a fresh release when the key is set, the file
of the last build otherwise, and it logs which). A whole build is one release even if someone presses Release meanwhile, and the build workers read the file instead of downloading
the bundle again. A renamed page answers its old /pages/<old-slug> with a permanent redirect from redirects() in next.config.ts. The Builder home page is at /pages/home, and the sitemap lists it there.
The layout reads the catalog settings with a one-year cache policy instead of the default hour, because a page lives only as long as its shortest read; without that Next would
render the release pages again every hour. A catalog change still re-renders pages through the signed revalidate webhook, as in live mode, from the same frozen release. The file is
in every server function that renders a page (not the /api webhook routes), and the build warns when it passes about 20 MB, so mind your host's function size limit. It keeps the cost rules of Keeping ISR costs down: no revalidate under an hour, no revalidatePath. See create-store for the option.