fcomursDocs

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

Diagram
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 toDo this
Start a new themenode scripts/theme.js new aurora, open themes/aurora/ in VS Code
Find mistakesnode 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 backtheme.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 storenode scripts/theme.js login --console, publish aurora (designers)
In a merchant's storeOnline store, Versions, Add theme, Customize (editor), Preview (your own browser only), Publish
Theme .zipIn 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 versionThe 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 publishtheme.js rollback aurora 1.0.0, or console, Templates, Coded themes, Make live
Go back to the old design in a storeThe 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:

WhoHowWhich 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 reponode 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.

bash
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.

CommandWhat it doesExit 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 once1 with errors, 0 with warnings only
check … --jsonThe 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

Diagram
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

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"] }
}
KeyRequiredMeaning
nameyes≤ 60 characters
versionyessemver 1.0.0; goes up with every publish
themeApiyesWhich format it's written in; only 1 for now
colorsnoOnly these four keys, hex colours
covernoThe theme library picture; the file must exist
templatesnoThe pages the theme designs; each needs templates/<name>.json. Other pages keep the merchant's existing design on install
requires.sectionsnoBuilt-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

JSON
{
  "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" } }
    ] }
  ]
}
RuleWhy
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

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.

HelperJob
if unless each with lookupHandlebars' own
eq ne gt lt and or notComparisons: {{#if (eq settings.align "center")}}
default{{default settings.heading "Welcome"}}
moneyA price in the store's currency
linesEach line of a text as its own item: {{#each (lines settings.items)}}
embed encodeVideo link, embed, URL encode
uidThis copy's own id: id="{{uid "slide"}}", slide-<section id>
assetThe 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

JavaScript
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

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)

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:

FilePlaceholders
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):

JSON
{ "settings": [], "uses": ["gsap", "scrolltrigger"] }
JavaScript
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 } });
}
usesIn fc
gsapfc.gsap
scrolltriggerfc.ScrollTrigger (brings gsap too)
motionfc.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.

tsx
// 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>
  ),
});
PartHow it works
settingsField 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.
blocksblock({ fields }, { label }); maxBlocks caps them (default 50).
dataServer 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.
renderServer 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.
ImportsOnly 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.
Typesnpm 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):

CheckExample message
Bad JSONtheme.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 idid "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 sectionThe 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, coloursthemeApi 9 isn't one this fcomurs can run
A bad settings schemaUnknown 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):

KindCheck
Isolationhtml/body/:root/* in section CSS; window.x =, document.querySelector in scripts
Duplicate idsA literal id="..." — use {{uid}}
PerformanceImages > 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
MobileA 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

bash
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
Diagram
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)
RuleHow
Any store, never livedev 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
Tokenlogin 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 computerWith --api https://…, --store <handle> is required and must match the token's store
pull / pushpull --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/):

StepWhat happens
PageresolvePage() — the list of sections from the theme's template; theme sections as theme:<name>, built-ins under their own type
SettingsmergeSettings() — settings.json defaults ← the theme's values ← the merchant's values
DataAll sections' data together, on the server (product/collection settings, objects)
HTMLHandlebars, on the server; each copy in a <div data-fc-s="<theme>-<section>">, with its scoped CSS
ScriptIn the browser, init(section, fc) for every copy; the cleanup it returns runs when the section goes away
MistakesIf 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).

bash
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
RuleMeaning
The theme's name = the folder's namethemes/aurora, aurora; it never changes
version must go up every timeThe same version again, or one older than the newest, refused (409)
A published version never changesIf it's wrong, publish a new version; the database takes no updates either
Rollback = only the "live" pointerNo version's files change; stores that installed earlier don't change either
--yesDoesn't ask — CI only (with FCOMURS_PUBLISH_TOKEN)
ConsoleTemplates, 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):

Diagram
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

WhatWhere
CLIscripts/theme.js (its name in messages and its default addresses: scripts/theme/defaults.js)
npm packagepackages/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
Checkingscripts/theme/check.js (JSON with line numbers: scripts/theme/json.js)
newscripts/theme/scaffold.js
login, dev, pull, pushscripts/theme/devClient.js
Package (scope, init, assets)apps/api/services/theme/{package,cssScope,script}.js
Dev route, tokenapps/api/controllers/themeDevController.js, middleware/themeDevAuth.js (Development theme = StoreTheme role development)
Rendererapps/storefront/lib/renderer/ (resolve.ts, handlebars.ts, storeTheme.ts), components/sections/SectionGuard.tsx
The admin's "Allow" pageapps/dashboard/app/theme-cli/page.tsx (dev), apps/console/app/theme-cli/page.tsx (publish)
Publish, rollbackCLI scripts/theme/publishClient.js; API services/theme/{publish,files}.js, controllers/themeRegistryController.js, middleware/themePublishAuth.js, models/{Theme,ThemeVersion,ThemeUpload}.js
ConsoleTemplates, Coded themes (apps/console/app/(console)/templates/CodeThemes.tsx)
.zipAPI 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 libraryAPI 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
TestsAPI: 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 sectionsAPI 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
Examplethemes/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.