Own your storefront

The storefront that ships with Forge is a reference implementation: complete, maintained by us, and a consumer of the read port exactly like anything you would write. Replacing it is a supported outcome, not an escape hatch.

The question is how far you want to go, and the three answers have very different costs.

1. Theme it

Colours, typography, logo, spacing. Tokens, and nothing else.

Cheap, upgrade-safe, and the version most customers should stop at. Your storefront keeps receiving our improvements because it is still our storefront.

2. Replace pieces

Swap a component, change a template, add a block into a slot. You own what you replaced; the rest keeps updating.

The honest warning: each piece you take over is a piece you maintain. Two or three is normal. Twenty means you have chosen option 3 without deciding to.

3. Own it entirely

Build your own front — Next, Astro, Remix, native, whatever. It talks to the same kernel through the same read port, with the same guarantees.

⚠️ “Theme” is only the visual layer. Rebuilding the checkout flow is not theming. If you find yourself rewriting behaviour rather than appearance, you are here, and it is better to know it.

What you get either way

The read port is designed as a public contract, not as an internal API the storefront happens to use. It answers in stable shapes with stable names and assumes nothing about a browser.

• GET /v1/read/<name> — anonymous, keyed by store. What a shopper’s browser may see.
• POST /v1/cart/commands/<name> and the sibling anonymous faces — the shopper journey, no credential; the cart id is the capability.

That is the whole surface a storefront needs. Nothing privileged, nothing hidden — the reference storefront uses exactly this and has no back door, because there is none to have.

Rules that survive whichever option you pick

Money is integer cents. Format at the edge, never store or compute a float.

The order snapshots. Title, price and address are copied into the order at the moment of the transaction. Do not re-read the product to render a past order — you would be showing today’s price for yesterday’s purchase.

Public reads are PII-safe, even for the holder. A guest reading their own checkout gets a masked buyer. Your front is the one that has what it typed; keep it, rather than expecting to read it back.

The store resolves the tenant. Pass store (the id) on every public read. There is no credential to infer it from, which is exactly why the face is safe to call from a browser.

What you give up

Our storefront improvements, for whatever you replaced. That is the whole cost — and it does not touch the kernel, which keeps upgrading regardless. See deploy & the fleet.