Throttle Builder
Throttle Builder is a marketplace extension where a merchant builds the pages, header, footer and announcement bar of a headless store with a visual editor, an API or an AI assistant. Your store reads what the merchant published and draws it with its own widgets. Nothing about the store's catalog, cart or checkout moves into the Builder.
The pieces
| Piece | What it is | Read more |
|---|---|---|
@usethrottle/builder | The headless client: reads published pages, header, footer, slots and site settings, with Next.js cache tags and the change-notice receiver. | The SDK |
@usethrottle/builder-react | Renders a page document as React: the provider, header, footer, slots, the page route and the sitemap. | Rendering |
@usethrottle/builder-schema | The page document, site settings, limits and widget definitions as zod schemas. Pure TypeScript, no React. | Document schema |
@usethrottle/storefront-react/builder | The catalog and commerce widget packs: product grids, shelves, carousels, search, cart and account widgets. | Widget guideline |
| MCP server | One address for an AI agent: connect with a key or by signing in, choose read, draft, publish or full, and the agent checks its own work in a browser. | MCP server |
| Widget API | Create, version, validate and switch off custom widgets with a secret key. | Widget API |
| Delivery modes | A store reads the Builder live, or from a frozen release at build time. | Delivery modes |
Images the merchant uploads live in the media library. The Builder freezes each one it uses, with its width variants, into the published page, so a store never calls Throttle for an image while rendering.
Versions: what a store must run
The Builder can place saved sections, interactions (tabs, accordion, carousel, show and hide), the countdown widget, entrance animation, custom CSS and code widgets. A store
must run @usethrottle/builder-react 0.4.0 or later and @usethrottle/builder-schema 0.2.1 or later
before a merchant or an AI agent uses any of them. Upgrade the store first.
| On 0.3.x of builder-react | What happens |
|---|---|
| A section with an interaction | Degrades: the columns are drawn as a plain row, every panel visible. |
| A countdown widget | Is empty. |
| Custom CSS | Is ignored. |
| A page that contains a saved-section reference | Fails to render. The page does not draw. |
| A code widget | Draws nothing and runs nothing: code needs the renderer of 0.4.0. |
Pages that use none of these draw exactly as before on every version, so upgrading changes nothing for them. If you manage a store for a merchant, upgrade before turning the code switch or an agent's level up.
Keys
| Key | Sent as | Use |
|---|---|---|
tb_pk_... | X-Builder-Key | Publishable. Reads published pages (and, with a preview token, drafts). Made on the Keys and AI agents screen with a channel: server (no Origin, for your backend and build), app (an Origin is optional), or browser (an exact list of allowed https origins, required). |
tb_sk_... | Authorization: Bearer | Secret. Drives the MCP server, the Widget API and the release routes, within the level it was given (read, draft, publish or full, plus a separate code switch). Refused when the request carries an Origin: it belongs on a server. |
A merchant has at most 20 active publishable keys and 2 active secret keys. A key is shown once, when it is made, and only its last four
characters afterwards. createBuilderClient refuses a tb_sk_ key.
Quick start: a live Next.js store
In live mode the store reads the Builder while it runs and clears its cache when the Builder sends a signed change notice. This is the default. For a store that reads a frozen release at build time instead, see Builder delivery modes.
npm install @usethrottle/builder @usethrottle/builder-react @usethrottle/storefront-react THROTTLE_BUILDER_KEY=tb_pk_... # a publishable key of the "server" channel. Server and build only.
THROTTLE_MEDIA_ORIGIN=https://... # the one origin Builder images may be served from
THROTTLE_BUILDER_WEBHOOK_SECRET=... # signs the change notices sent to /api/throttle/builder-revalidate // lib/builder.ts
import { createBuilderClient } from '@usethrottle/builder';
export const builder = createBuilderClient({ builderKey: process.env.THROTTLE_BUILDER_KEY! }); // lib/packs.ts
import { catalogPack, commercePack } from '@usethrottle/storefront-react/builder';
export const createPacks = () => [
catalogPack({ catalogKey: process.env.THROTTLE_CATALOG_SERVER_KEY || process.env.NEXT_PUBLIC_THROTTLE_CATALOG_KEY || '' }),
commercePack(),
]; // app/layout.tsx (a server component)
import { loadSite } from '@usethrottle/builder-react/server';
import { CATALOG_SLOT_POINTS } from '@usethrottle/storefront-react/builder';
import { builder } from '@/lib/builder';
import { createPacks } from '@/lib/packs';
import { Providers } from './providers';
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const site = await loadSite({
client: builder,
locale: 'en',
slots: CATALOG_SLOT_POINTS.map((slot) => slot.name),
packs: createPacks(),
mediaOrigin: process.env.THROTTLE_MEDIA_ORIGIN ?? '',
});
return (
<html lang="en">
<body>
<Providers site={site}>{children}</Providers>
</body>
</html>
);
} // app/providers.tsx
'use client';
import { BuilderProvider, BuilderHeader, BuilderFooter } from '@usethrottle/builder-react';
import type { LoadedSite } from '@usethrottle/builder-react';
import { createPacks } from '@/lib/packs';
const packs = createPacks();
export function Providers({ site, children }: { site: LoadedSite; children: React.ReactNode }) {
return (
<BuilderProvider packs={packs} site={site}>
<BuilderHeader />
{children}
<BuilderFooter />
</BuilderProvider>
);
} // app/pages/[handle]/page.tsx
import { createBuilderPage } from '@usethrottle/builder-react/next';
import { builder } from '@/lib/builder';
import { createPacks } from '@/lib/packs';
const route = createBuilderPage({
fromParams: 'handle',
client: builder,
packs: createPacks(),
storeUrl: process.env.NEXT_PUBLIC_SITE_URL!, // your store's origin, for the canonical link
mediaOrigin: process.env.THROTTLE_MEDIA_ORIGIN ?? '', // the same value as loadSite, for og:image
});
export default route.Page;
export const generateMetadata = route.generateMetadata; // app/api/throttle/builder-revalidate/route.ts
import { createRevalidateHandler } from '@usethrottle/builder/next';
export const POST = createRevalidateHandler({ secret: process.env.THROTTLE_BUILDER_WEBHOOK_SECRET });
In the Builder, open Store webhooks and add an endpoint: left empty, its URL is your store address followed by /api/throttle/builder-revalidate, the route above. The secret it shows once is THROTTLE_BUILDER_WEBHOOK_SECRET. Without it, a published change
reaches the store only when the hour-long cache runs out. Each part is explained on its own page: rendering, the SDK.
THROTTLE_BUILDER_KEY in your server environment only, never in a NEXT_PUBLIC_ variable.
A server-channel key refuses any request that carries an Origin, so a browser could not use it anyway.
What it costs your host
The Builder is built so a store pays close to nothing for it on a host that bills for cached pages.
- Live mode. Every Builder read is cached for at least an hour (
revalidate: 3600, with no option for less). A change notice clears only the cache tags of what changed, so a page edit refreshes that page and not the whole site. Publishing the site (theme, menus, brand, announcement) or the header or footer is different: every page reads those, so every page you then visit is rebuilt once. The catalog product pages prerender no product by default (staticParamsis 0, and the cap is 50), and a Builder page is rendered on its first visit. - Build mode. One full build per release and no Builder-driven ISR writes. Every page of the release is generated at build, on purpose.
The cost rules of the catalog routes are in Keeping ISR costs down.
Build with an AI agent
Connect an AI agent with one address, https://builder.usethrottle.dev/mcp: claude.ai and Claude desktop sign in with that address alone, and coding tools (Claude Code, Cursor, VS Code, Windsurf) add a key.
The agent reads your store, edits the draft, opens a preview link in a browser of its own at 390, 768 and 1280 px, and publishes only if you gave it the Publish or Full level.
Start at Connect an AI agent.
For merchants and for authors of widgets
- Widget guideline: write a widget pack, a data source, link targets, slots and migrations.
- Widget API: endpoints, errors, the Throttle Template reference, the CSS rules and the limits.
- Document schema: the page document, its limits and the edit operations.
- Merchant guides, in plain language: set up Throttle Builder, live or build-time delivery, search and sharing and custom pages.