Developers / Throttle Builder

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

PieceWhat it isRead more
@usethrottle/builderThe 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-reactRenders a page document as React: the provider, header, footer, slots, the page route and the sitemap.Rendering
@usethrottle/builder-schemaThe page document, site settings, limits and widget definitions as zod schemas. Pure TypeScript, no React.Document schema
@usethrottle/storefront-react/builderThe catalog and commerce widget packs: product grids, shelves, carousels, search, cart and account widgets.Widget guideline
MCP serverOne 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 APICreate, version, validate and switch off custom widgets with a secret key.Widget API
Delivery modesA 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-reactWhat happens
A section with an interactionDegrades: the columns are drawn as a plain row, every panel visible.
A countdown widgetIs empty.
Custom CSSIs ignored.
A page that contains a saved-section referenceFails to render. The page does not draw.
A code widgetDraws 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

KeySent asUse
tb_pk_...X-Builder-KeyPublishable. 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: BearerSecret. 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.

Install
npm install @usethrottle/builder @usethrottle/builder-react @usethrottle/storefront-react
.env.local and your host
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
One client for the server
// lib/builder.ts
import { createBuilderClient } from '@usethrottle/builder';

export const builder = createBuilderClient({ builderKey: process.env.THROTTLE_BUILDER_KEY! });
The widget packs
// 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(),
];
One read for the layout
// 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>
  );
}
The provider, in a client module
// 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>
  );
}
The route of a Builder page
// 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;
The change-notice endpoint
// 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.

Keep the key off the browser
Put 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 (staticParams is 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