Developers / Throttle Builder

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 showsSoon 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 readsAt 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.
PagesRendered 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 hostISR 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.
ClientcreateBuilderClient({ 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

Build mode 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.

KeyUse
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.
Keep the build key off the browser
Put 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

Every release page, generated at build
// 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:

Scaffold a build-mode store
npx @usethrottle/create-store my-store --builder-mode build
.env.local and your host
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.