Custom themes & the fork lifecycle

A custom theme is a merchant’s own, fully code-editable theme. It’s created by forking the platform starter — a complete, blank-slate Liquid theme.

What a fork is

• Its code (Liquid views, CSS, JS, locales, theme.json) lives as editable files in the store, reachable through the dashboard code editor and the CLI.
• It records the starter version it was forked from. That version is what drives everything below, so a fork ages predictably.
• The locked checkout / order-confirmation pages are not part of a fork — they always render from the platform. A fork can’t ship them.

Draft, preview, publish

Editing a fork writes to a draft. The live storefront serves the published version; you preview the draft with ?previewTheme=<id> (the CLI’s dev prints it). Publishing promotes the draft through the Quality Gate.

• Code edits → draft. New files → live (additive-safe). Reset a file → draft.
• Every file keeps revision history; you can roll a file back (as a draft) and review before publishing.

Reset to starter

Any starter-derived file has a pristine version you can restore — the merchant’s escape hatch when a file gets edited into a broken state. Reset restores the file as it was in the fork’s starter era (not whatever the current starter is), so you never paste newer starter markup into an older fork. The restore lands as a draft for review.

Missing pages fall back gracefully

If the platform later adds a page type your fork predates, the fork has no template for it. Instead of an error, the page renders from the starter — pinned to your fork’s era for pages it had, and from the current starter for genuinely new page types — wrapped in your fork’s own layout and chrome. The code editor lists these as “using platform default; create the file to customize.”

Starter updates

When the platform ships a new starter, your fork surfaces a “starter update available” signal (a minor/major difference from your fork’s era). Your fork keeps working exactly as-is; the signal is your cue to review what changed and adopt the parts you want.