Theme Developer Guide
First time? Read theme-tutorial.en.md first: from installing Node to publishing, step by step, with one complete example section. This guide is the full reference after it.
Status: complete (Phases 1–5) — the theme folder, check, dev (a Development theme on any store), pull/push, publish/rollback to the registry, and Add / Customize / Preview / Publish / .zip / Update in a store's Versions. For now only the fcomurs team (first-party) builds themes.
In plain words — the whole thing on one page
You (VS Code) fcomurs registry A merchant's store: Online store ───────────── ──────────────── ──────────────────────────────── themes/aurora/ ┌ Live (what shoppers see) — the top card check ─ finds mistakes └ Versions — everything in one table: dev ─ a "Development" theme on a store ─────────────────────────► Development · Draft theme · publish ─────────────────────────────► aurora 1.0.0 ──Add theme──► versions of your design · previous live pull / push ◄──── the store's theme ⇄ folder ──────────────────────► Customize · Preview · Publish · ⋯
| You want to | Do this |
|---|---|
| Start a new theme | node scripts/theme.js new aurora, open themes/aurora/ in VS Code |
| Find mistakes | node scripts/theme.js check aurora |
| Work on it inside a store (without touching live) | node scripts/theme.js login (Allow in the dashboard), node scripts/theme.js dev aurora, open the preview link it gives; every save reloads in ~1 second. A "Development" row appears in the store's Versions — shoppers see nothing |
| Bring a store's theme into a folder / send it back | theme.js pull "Starter", folder; after changes theme.js push themes/starter --theme "Starter" (the live theme only with --live, and it asks first) |
| Give it to every store | node scripts/theme.js login --console, publish aurora (designers) |
| In a merchant's store | Online store, Versions, Add theme, Customize (editor), Preview (your own browser only), Publish |
| Theme .zip | In Versions, the theme row's ⋯, Download (.zip); Add theme, Upload .zip — the same check, file:line on mistakes, nothing added (needs Custom code access) |
| fcomurs ships a new version | The row says "Update to 1.1.0 available", shows what will change, Make the updated copy — a new copy in Versions, the merchant's own stays exactly as it is; their changes (settings, removed sections, their own sections, order) carry over |
| Undo a wrong publish | theme.js rollback aurora 1.0.0, or console, Templates, Coded themes, Make live |
| Go back to the old design in a store | The live coded theme's ⋯, Switch back to your own design |
The live theme never changes by itself. A theme never touches the store's own pages (About, policies), landing pages, products or orders.
The whole theme is written in your own VS Code, in this repo's themes/<name>/ folder. When a merchant installs it, a copy of the theme goes to their store, and every section can be changed in the editor.
1.Getting started
Two ways to run it, the same commands:
| Who | How | Which server |
|---|---|---|
| Any developer (no fcomurs repo) | The npm package fcomurs-theme: npm create fcomurs-theme@latest <name>, then npx fcomurs-theme <command> in the theme folder (or npm run dev/check) | Live fcomurs by default (api.fcomurs.com); login/dev/pull/push need --store <handle> |
| Inside the fcomurs repo | node scripts/theme.js <command>; themes live in themes/<name> | The dev servers on your computer by default |
From the very start, step by step: theme-tutorial.en.md. The examples below use the repo's command; with the package, write npx fcomurs-theme in place of node scripts/theme.js, and leave out the theme's name to mean the folder you're in.
node scripts/theme.js new aurora # makes themes/aurora node scripts/theme.js check aurora # every mistake, with file:line:column
A theme from new passes check straight away. For a complete example, see themes/starter.
| Command | What it does | Exit code |
|---|---|---|
new <name> | A small theme in themes/<name> (home + product, one section of its own) | 0; 2 for a bad name or an existing folder |
check <name|folder> | Every check in §6, all mistakes at once | 1 with errors, 0 with warnings only |
check … --json | The same, as JSON (for CI or an editor) | the same |
login [--store h] [--no-browser] | "Allow" in the store admin, an 8-hour theme dev token (§7) | 0 / 2 |
dev <name|folder> [--store h] [--once] | check, push to the development store, push again on every save (§7) | --once: 0 when pushed, 1 with errors |
check needs no server or database — only Node.
2.The folder
themes/aurora/ ├── theme.json name, version, themeApi, colours, templates, requires ├── templates/ which sections each page has, in what order │ ├── home.json │ └── product.json … ├── sections/<name>/ the theme's own sections │ ├── section.html Handlebars template │ ├── style.css applies to this section only │ ├── script.js export default function init(section, fc) │ └── settings.json what the merchant can change in the editor ├── blocks/<name>/ the same format (block.html, settings.json …) ├── layout/ header/footer .html .css .js ├── assets/ images, svg, fonts ├── migrations/ rules for updates (Phase 5) ├── site.css CSS for the whole page (fonts, body …) └── site.js
Section and block folder names: lower-case letters, digits and - (hero-split). Built-in sections have _ in their names (product_grid), so the two never get mixed up.
3.theme.json
{
"name": "Aurora",
"version": "1.0.0",
"themeApi": 1,
"description": "Big pictures, few words",
"category": "Fashion",
"author": "fcomurs",
"cover": "assets/cover.jpg",
"colors": { "buttonColor": "#111111", "primaryColor": "#111111", "navbarColor": "#ffffff", "backgroundColor": "#ffffff" },
"templates": ["home", "product", "collection", "cart"],
"requires": { "sections": ["product_main", "collection_main", "product_grid"] }
}| Key | Required | Meaning |
|---|---|---|
name | yes | ≤ 60 characters |
version | yes | semver 1.0.0; goes up with every publish |
themeApi | yes | Which format it's written in; only 1 for now |
colors | no | Only these four keys, hex colours |
cover | no | The theme library picture; the file must exist |
templates | no | The pages the theme designs; each needs templates/<name>.json. Other pages keep the merchant's existing design on install |
requires.sections | no | Built-in sections the theme can't work without |
Template names: home, product, collection, collections, shop, featured, brand, blog, article, cart, wishlist, track, account.
4.Templates
{
"sections": [
{ "id": "hero", "type": "hero-split", "settings": { "heading": "New season" } },
{ "id": "new", "type": "product_grid", "settings": { "sort": "newest", "count": 8 } },
{ "id": "promises", "type": "feature-list", "blocks": [
{ "type": "feature", "settings": { "title": "Your promise here" } }
] }
]
}| Rule | Why |
|---|---|
Every section has a stable id (letters, digits, -, _; once per template) | On updates fcomurs matches the merchant's changes and the theme's changes by id — change an id and it's a "new section" |
type = the theme's sections/<name> or a built-in section (product_grid, hero …) | |
settings holds only that section's settings; keys starting with _ (the Style tab: _paddingTop …) always work | |
A page template must have that page's main section (product, product_main, cart, cart_main …) | That's what draws the product/cart |
Some built-ins only work on certain pages (related_products only on product) | check says so |
The list of built-in sections and their settings: apps/storefront/sections/<type>/schema.json, or the storefront's /dev/sections gallery.
5.Sections
section.html — Handlebars
<div class="hero hero--image-{{settings.imageSide}}"> <h1>{{settings.heading}}</h1> {{#if settings.buttonLabel}}<a class="hero__button" href="{{settings.buttonLink}}">{{settings.buttonLabel}}</a>{{/if}} <img src="{{asset "hero.svg"}}" alt="" width="800" height="800"> <ul>{{#each blocks}}<li>{{settings.title}}</li>{{/each}}</ul> </div>
What a template gets: settings (this section's), blocks (each with its settings), store (name, logo, phone, email, address, currencySymbol). Product/collection settings arrive as objects. Everything printed is auto-escaped.
| Helper | Job |
|---|---|
if unless each with lookup | Handlebars' own |
eq ne gt lt and or not | Comparisons: {{#if (eq settings.align "center")}} |
default | {{default settings.heading "Welcome"}} |
money | A price in the store's currency |
lines | Each line of a text as its own item: {{#each (lines settings.items)}} |
embed encode | Video link, embed, URL encode |
uid | This copy's own id: id="{{uid "slide"}}", slide-<section id> |
asset | The address of a theme asset: {{asset "hero.jpg"}} |
There are no other helpers — check errors on an unknown helper ("did you mean" when a close name exists).
style.css
Applies to this section only — fcomurs puts the section's own prefix before every rule (Phase 2). So don't write html, body, :root or * here; those go in site.css. Assets: url("../assets/x.svg").
script.js
export default function init(section, fc) { const button = section.querySelector('.hero__button'); const onClick = () => {}; button?.addEventListener('click', onClick); return () => button?.removeEventListener('click', onClick); // cleanup }
Runs once for every copy of the section; section = that copy's element. No document.querySelector or window.x = … — those reach other sections. JS never runs on the server.
settings.json
{
"settings": [
{ "key": "heading", "label": "Heading", "kind": "text", "default": "Made to last" },
{ "key": "imageSide", "label": "Image on the", "kind": "select", "default": "right",
"options": [{ "value": "left", "label": "Left" }, { "value": "right", "label": "Right" }] }
],
"blocks": [
{ "type": "feature", "label": "Feature", "fields": [{ "key": "title", "label": "Title", "kind": "text" }] }
],
"max_blocks": 6
}kind: text · textarea · richtext · image · url · select · number · range · checkbox · color · datetime · product · collection · collections · form.
| Rule | |
|---|---|
key starts with a letter; letters/digits/_; once only | |
select needs options; default must be one of them | |
range/number: min ≤ max, default between them | |
A checkbox's default is true/false | |
No label gives a warning (the merchant would see the key) |
Header and footer — layout/
With layout/header.html and layout/footer.html, the theme brings its own header/footer — in place of the store's (in preview, live and in the editor). Without them the store's own stays. These aren't Handlebars — they fill placeholders like the store's code header:
| File | Placeholders |
|---|---|
header.html | {{logo}} {{store_name}} {{menu}} {{search}} {{cart_count}} {{phone}} {{email}} |
footer.html | {{logo}} {{store_name}} {{about}} {{categories}} {{quick_links}} {{info_links}} {{support_links}} {{extra_links}} {{social}} {{phone}} {{email}} {{address}} {{copyright}} {{year}} |
header.css/footer.css are whole-page CSS (no scope); header.js/footer.js are export default function init(section, fc) like sections, with section = the header or footer. check warns on unknown placeholders. While customising a coded theme in the editor, the header/footer can't be changed (it's the theme's code, or the store's own design).
Animation — GSAP and Motion in script.js
Ask for the libraries in settings.json; the store loads them only on pages with a section that asked, from its own bundle (no CDN):
{ "settings": [], "uses": ["gsap", "scrolltrigger"] }export default function init(section, fc) { if (fc.reducedMotion) return; fc.gsap.from(section.querySelectorAll('.card'), { y: 24, opacity: 0, stagger: 0.08, scrollTrigger: { trigger: section } }); }
uses | In fc |
|---|---|
gsap | fc.gsap |
scrolltrigger | fc.ScrollTrigger (brings gsap too) |
motion | fc.motion — animate, scroll, inView, stagger |
Everything a script starts with them stops by itself when the section goes away (a GSAP context; every Motion animation). fc.reducedMotion is true for shoppers who turned motion off — check warns when a script animates without looking at it. A script that uses GSAP or Motion without listing it in uses is an error.
React sections — section.tsx
A section can be a React component instead of section.html + settings.json + script.js. One theme can have both kinds. fcomurs-theme new <name> --react makes a theme with one.
// sections/hero/section.tsx
import { defineSection, text, image, collection, block, Image, Money } from '@fcomurs/theme';
import AddButton from '../../components/AddButton'; // 'use client' — an island
export default defineSection({
name: 'Hero',
settings: {
heading: text({ label: 'Heading', default: 'New season' }),
picture: image({ label: 'Picture', phone: true }),
collection: collection({ label: 'Collection' }),
},
blocks: { badge: block({ label: text() }, { label: 'Badge' }) },
async data({ settings, store }) {
return { products: await store.products({ collection: settings.collection?.slug, limit: 4 }) };
},
render: ({ settings, blocks, data }) => (
<section className="hero">
<h1>{settings.heading}</h1>
<Image src={settings.picture} alt="" />
{blocks.map((b) => <span key={b.id}>{b.settings.label}</span>)}
{data.products.map((p) => <p key={p.id}>{p.title} <Money amount={p.price} /> <AddButton productId={p.id} /></p>)}
</section>
),
});| Part | How it works |
|---|---|
settings | Field builders: text textarea richtext url color datetime checkbox number range select image product collection collections. The editor's panel comes from them — there's no settings.json. Types follow: settings.heading is a string, settings.collection a Collection | null. |
image({ phone: true }) | Adds an optional phone picture; the value is { src, phone }. <Image src={…} /> shows phone up to 639px wide. |
blocks | block({ fields }, { label }); maxBlocks caps them (default 50). |
data | Server only, before render. store.products({ collection, sort, limit ≤ 24 }), store.product(slug), store.collection(slug) (with 12 products), store.collections() (without products). At most 20 calls, 5 seconds. |
render | Server only, once per page view: its HTML goes to the browser as it is and is never drawn again. |
'use client' | A file that starts with it holds client components: drawn on the server with the section, then woken up in the browser ("islands"). Only these ship JavaScript. Props must be plain data (functions are dropped); server-drawn children are kept as they are. Use useState, effects, Motion, GSAP here. |
| Imports | Only the theme's own files (sections/, components/, lib/, islands/) and react, react-dom, motion, motion/react (framer-motion is the same), gsap, gsap/ScrollTrigger, @fcomurs/theme. No CSS imports — style.css next to section.tsx is scoped as before; Tailwind's output goes in site.css. |
| Types | npm install @fcomurs/theme react motion and @types/react (a --react project has them) — VS Code then completes settings, data and store. |
Building: fcomurs compiles the TSX itself on every dev push, push, upload and publish. Mistakes come back with file and line (sections/hero/section.tsx:12: …) — in the terminal, and in a red panel on the open preview; the preview keeps the last good save until you fix it.
Safety: a theme's server code never runs in the store's server. It runs in a separate worker process with no environment variables, no files and no child processes, in an empty JavaScript context of its own (no process, require, fetch or eval). A section that throws, runs over a second, or uses too much memory is left out of the page; the rest still draws.
Motion tip: what a client component draws on the server is its first frame — initial={{ opacity: 0 }} starts hidden until the browser wakes it. For text at the very top of a page, use initial={false} or a short animation.
6.What check looks at
Errors (exit 1):
| Check | Example message |
|---|---|
| Bad JSON | theme.json:4:3 Unexpected """ — a comma or "}" was expected (is a comma missing?) |
| Handlebars syntax, unknown helper | "mony" isn't a helper — did you mean "money"? |
Missing asset ({{asset}}, CSS url()) | assets/nope.png doesn't exist |
| Unknown section type | "product_gird" is neither … — did you mean "product_grid"? |
Duplicate section id | id "a" is used twice in this template (first on line 4) |
| A built-in section on the wrong page | "product_main" only works in the product template |
| A page without its main section | The product page needs its main section |
An unknown section in requires.sections | "mega_menu" isn't a built-in section of this fcomurs |
themeApi, version, colours | themeApi 9 isn't one this fcomurs can run |
| A bad settings schema | Unknown kind, no options, default not among the options, duplicate key |
| An unknown setting or a bad select value in a template | "intro" has no setting "headline" — did you mean "heading"? |
| Images > 2 MB |
Warnings (exit 0, but fix them):
| Kind | Check |
|---|---|
| Isolation | html/body/:root/* in section CSS; window.x =, document.querySelector in scripts |
| Duplicate ids | A literal id="..." — use {{uid}} |
| Performance | Images > 500 KB; a section's CSS+JS > 30 KB; the theme's total JS/CSS > 150 KB; <img> without loading="lazy" (except in the page's first section) or without width/height |
| Mobile | A fixed width above 600px |
| Accessibility | <img> without alt; <a>/<button> without text or aria-label; <input> without a label; skipped heading levels (h2, h4) |
7.Running it in a store — login, dev, pull, push
node scripts/theme.js login # opens the store admin in a browser → Allow node scripts/theme.js dev starter # push, then again on every save
Save in VS Code ──► theme.js dev ──► check (errors? → nothing is pushed, the store shows the last good one) └► PUT /api/theme-dev/theme ──► API builds the package (CSS scope, script → init, asset addresses) ──► DevTheme The store page you have open ◄── checks the revision every second, reloads when it changes (~1 second)
| Rule | How |
|---|---|
| Any store, never live | dev makes the folder your Development theme (in the store's Versions, one per developer); every push changes that one; it's seen only through the preview link (8 hours). It can't be published — Duplicate it and publish the copy |
| Token | login gets an 8-hour token from the admin's "Allow" — theme dev routes only, that store only, with Custom code access. Kept in ~/.fcomurs/theme-credentials.json (readable by the user only), never in the repo. In CI: FCOMURS_THEME_TOKEN |
| A server other than this computer | With --api https://…, --store <handle> is required and must match the token's store |
pull / push | pull --list lists the store's themes; pull <name|id> [folder] (into an empty folder); push <folder> --theme <name|id> — the folder's code and pages into that theme (into live only with --live) |
How a theme's sections are drawn in a store (apps/storefront/lib/renderer/):
| Step | What happens |
|---|---|
| Page | resolvePage() — the list of sections from the theme's template; theme sections as theme:<name>, built-ins under their own type |
| Settings | mergeSettings() — settings.json defaults ← the theme's values ← the merchant's values |
| Data | All sections' data together, on the server (product/collection settings, objects) |
| HTML | Handlebars, on the server; each copy in a <div data-fc-s="<theme>-<section>">, with its scoped CSS |
| Script | In the browser, init(section, fc) for every copy; the cleanup it returns runs when the section goes away |
| Mistakes | If a template is wrong or a section throws, only that section is left out of the store; the rest of the page is drawn |
CSS scope (API services/theme/cssScope.js): .x, [data-fc-s="…"] .x, :scope = the section itself, html/body/:root, the section, the section's prefix on @keyframes and @font-face names, url(../assets/x), the theme asset's address, @import removed.
8.Publish and rollback
Only fcomurs designers (a super admin in the console, or someone marked designer on the Team page).
node scripts/theme.js login --console # Allow in the console → a 1-hour publish token node scripts/theme.js publish aurora # shows the theme, version and server, asks for y node scripts/theme.js publish aurora --draft # made, but not live node scripts/theme.js rollback aurora 1.2.0 # which version is live — only that changes
| Rule | Meaning |
|---|---|
| The theme's name = the folder's name | themes/aurora, aurora; it never changes |
version must go up every time | The same version again, or one older than the newest, refused (409) |
| A published version never changes | If it's wrong, publish a new version; the database takes no updates either |
| Rollback = only the "live" pointer | No version's files change; stores that installed earlier don't change either |
--yes | Doesn't ask — CI only (with FCOMURS_PUBLISH_TOKEN) |
| Console | Templates, Coded themes: every theme's versions, who published when, "Make live". Every publish and change goes to the Activity log |
Why publishing is safe (R2 and the database can't share a transaction):
CLI: check ──► sha256 of every file ──► "Publish? (y/N)" └► POST uploads {manifest} ──► PUT only what the server doesn't have (by hash) Server: refuse when a hash doesn't match ──► finish: 4 hash every staged file again 5 check the whole theme again (doesn't trust the CLI's check) 6 assets → themes/<key>/<version>/, read back and hashed again 7 write the ThemeVersion ← nobody sees it yet 8 Theme.currentVersion = this ← one update = "publish" 9 delete the staging
Stopping anywhere before 8 publishes nothing. Stopping at 6 deletes the copied assets; stopping after 7 keeps the version but doesn't make it live (rollback can make it live). An hourly job deletes half-finished uploads (after a day).
Assets: with R2, R2_PUBLIC_URL/themes/<key>/<version>/<file>; without, the API's /api/theme-assets/<key>/<version>/<file> (THEME_FILES_DIR, default apps/api/theme-files/). Cached forever — a version's files never change.
9.Where the code is
| What | Where |
|---|---|
| CLI | scripts/theme.js (its name in messages and its default addresses: scripts/theme/defaults.js) |
| npm package | packages/theme-cli (fcomurs-theme): build.mjs bundles the repo's CLI and its check (apps/api/services/theme/*, the built-in section list, Handlebars, fflate) into one file, with src/defaults.js (live fcomurs, the folder you're in) in place of defaults.js. packages/create-fcomurs-theme (npm create fcomurs-theme) only asks for a name and runs new, with project files (package.json, .gitignore, README — not part of the theme; check/dev leave them out) |
| The format's lists (templates, helpers, kinds, limits) | scripts/theme/format.js — server-side validation uses the same |
| Checking | scripts/theme/check.js (JSON with line numbers: scripts/theme/json.js) |
new | scripts/theme/scaffold.js |
login, dev, pull, push | scripts/theme/devClient.js |
| Package (scope, init, assets) | apps/api/services/theme/{package,cssScope,script}.js |
| Dev route, token | apps/api/controllers/themeDevController.js, middleware/themeDevAuth.js (Development theme = StoreTheme role development) |
| Renderer | apps/storefront/lib/renderer/ (resolve.ts, handlebars.ts, storeTheme.ts), components/sections/SectionGuard.tsx |
| The admin's "Allow" page | apps/dashboard/app/theme-cli/page.tsx (dev), apps/console/app/theme-cli/page.tsx (publish) |
| Publish, rollback | CLI scripts/theme/publishClient.js; API services/theme/{publish,files}.js, controllers/themeRegistryController.js, middleware/themePublishAuth.js, models/{Theme,ThemeVersion,ThemeUpload}.js |
| Console | Templates, Coded themes (apps/console/app/(console)/templates/CodeThemes.tsx) |
| .zip | API services/theme/archive.js (fflate; path, count and unpacked size checked first), storeThemeController download/upload; check now lives in apps/api/services/theme/check.js (the CLI runs the same) |
| A store's theme library | API models/StoreTheme.js, controllers/storeThemeController.js (/online-store/store-themes, /online-store/public/store-theme); dashboard components/online-store/CodedThemes.tsx, editor ?storeTheme=<id>&template=<page>; storefront lib/renderer/devTheme.ts fetchStoreTheme |
| Tests | API: test/theme/{check,package}.test.js, test/saas/themeDev{,Cli}.test.js, test/saas/themeRegistry.test.js, test/saas/themePublishCli.test.js, test/saas/storeThemes.test.js, test/saas/storeThemeZip.test.js, test/saas/storeThemeUpdate.test.js, test/theme/merge.test.js; storefront: test/renderer.test.mjs |
| React sections | API services/theme/tsx.js (esbuild: the theme's files only, allowed imports, 'use client', island markers on the server and one fc-islands.js for the browser), schemaWorker.js + isolated.js (settings read in a locked-down process); storefront lib/renderer/renderTsx.server.ts + tsxWorker.cjs (drawing; registered in instrumentation.ts), islands.ts (waking islands), app/theme-render/route.ts (the editor's preview); SDK packages/theme-sdk (@fcomurs/theme; apps/api/services/theme/sdk.js is a copy that must stay identical — a test checks) |
Animation (uses) | storefront lib/animationKit.ts; uses in config/codeSectionSchema.js |
| Tests (React, animation) | API test/theme/tsx.test.js, test/saas/themeDev.test.js (the error panel); storefront test/renderTsx.test.mjs, test/animationKit.test.mjs |
| Example | themes/starter; a React one: fcomurs-theme new <name> --react |
When a new helper, setting kind or template is added, change format.js — and this guide.
Releasing the npm package: when the format, the check or the built-in sections change, release the package too, or outside developers keep checking against the old rules. Raise version in packages/theme-cli/package.json, cd packages/theme-cli && pnpm install && npm publish (prepublishOnly builds it). If create-fcomurs-theme changed, publish it as well. Both are published from fcomurs's npm account.
