Product Catalog / Storefront components

create-store

@usethrottle/create-store writes a complete Next.js store on @usethrottle/storefront-react: the shop, collections, categories, tags, product, search and account pages, the cart drawer, and the cache-safe webhook and sync routes.

Usage

Create a store
# A new Next.js store, with both keys asked for:
npx @usethrottle/create-store my-store

# Add the package to an existing app instead:
pnpm add @usethrottle/storefront-react @usethrottle/catalog @usethrottle/money

pnpm create @usethrottle/store my-store does the same. The folder must be empty or missing (default my-store). The command asks for your keys, writes .env.local, and installs dependencies with the package manager that ran it.

The two key prompts

A catalog has a browser key and a server key, and a store needs both (see the two catalog keys). The command asks for them in this order:

  1. "Catalog publishable key (pc_pk_...)": the browser key. It goes to NEXT_PUBLIC_THROTTLE_CATALOG_KEY.
  2. "Catalog server key, for your store's server (pc_pk_..., press enter to skip)": the server key. It goes to THROTTLE_CATALOG_SERVER_KEY. You can skip it, and the command warns that your server cannot read with only a browser key; add it to .env.local before you run the store.

Both start with pc_pk_, so the command asks the catalog which is which (a read with and without a website origin) and never trusts the order you typed them in. If you give a server key first, it asks for the browser key next. If you give them the wrong way round with flags and the catalog confirms it, it swaps them. If the catalog cannot place a key (offline, or no answer), it asks for both and takes the roles on your word, with a note.

A server key is never written as a NEXT_PUBLIC variable
The one rule the command enforces last, whatever path it took: a key the catalog says is a server key is never placed in NEXT_PUBLIC_THROTTLE_CATALOG_KEY, because that variable is published to every visitor. A secret key (pc_sk_) is refused outright; a storefront never uses one.
What .env.local ends up holding
# .env.local
# Browser key: sent to the browser. The catalog answers it only from your allowed websites.
NEXT_PUBLIC_THROTTLE_CATALOG_KEY=pc_pk_...
# Server key: your server reads with it. NEVER a NEXT_PUBLIC_ variable.
THROTTLE_CATALOG_SERVER_KEY=pc_pk_...
NEXT_PUBLIC_SITE_URL=https://shop.example
THROTTLE_WEBHOOK_SECRET=whsec_...

Options

OptionMeaning
[dir]Where to create the store (default my-store). Must be empty or missing.
--catalog-key <key>The catalog browser key. A server key given here is detected.
--server-key <key>The catalog server key, for reads made by your store server. Asked for after the browser key when missing.
--yes, -yAsk nothing. Needs --catalog-key. A server key given alone needs the browser key too, and keys the catalog cannot tell apart need both flags.
--builder-mode <live|build>Default live (nothing added). build adds a Throttle Builder site generated at build time from a frozen release, with no Builder reads while the store runs. See Builder delivery modes.
--pm <pnpm|npm|yarn|bun>The package manager (default: the one running the command).
--skip-installWrite the files and stop before installing.
--offlineDo not call the catalog to tell the keys apart. Then pass both --catalog-key and --server-key.

What you get

FileWhat it does
lib/store.tsThe server key (falling back to the browser key), your origin, and the preview token when THROTTLE_PREVIEW=1. Every route helper takes it.
app/providers.tsxStorefrontNextProvider and StoreFrame around every page, with generationWatch at 60 s.
app/layout.tsxLoads the settings on the server and imports the stylesheet.
app/page.tsx, shop, collections, c, tags, p, search, accountOne three-line route file per page, from the route helpers. The home is the shop; replace it when you have your own.
app/api/throttle/revalidate, app/api/throttle/syncThe signed webhook handler and the open-tab sync handler.
proxy.tsMoves the dashboard preview token into a cookie. It runs only for a request carrying the token.
README.md, AGENTS.mdHow the store stays cheap on Vercel, and notes for a coding agent working in it.

The store renders its pages per request from catalog data kept until the catalog changes, so it writes no ISR. Its README.md lists the cost rules; the reasons are on Keeping ISR costs down. Set THROTTLE_WEBHOOK_SECRET and point the catalog's storefront.changed webhook at /api/throttle/revalidate before you go live.

--builder-mode build

The store gains app/pages/[handle]/page.tsx (every page of the release through generateStaticParams, dynamicParams = false), lib/builder.ts (the build client), lib/packs.ts, and a layout, provider and next.config.ts that read the site from the release. Set THROTTLE_BUILDER_KEY (the build key, server and build only) and THROTTLE_MEDIA_ORIGIN; BUILDER_RELEASE_ID builds an older release. The build reads the release once into .builder/release.json and the running store never calls the Builder. Its README says one full build per release, zero Builder-driven ISR writes. Without the option the store is exactly as before.