Template kit

The kit turns a folder of real .tsx files — with syntax highlighting, Prettier, git diffs and npm imports — into the data.json (TemplateData) a store renders. Scaffold it with the CLI:

feeef template init my-template --blank
cd my-template && feeef use <store-slug>

Package layout

Each theme is a Node.js package:

my-template/
  feeef.template.json         # manifest: name, version, page order
  schema.ts                   # theme-owned editor schema overlay → dist/schema.json
  props.json                  # root props defaults (theme mode, corners, …)
  design-system.md            # the theme's visual contract (colors, motion, components)
  shared/components/<id>.tsx  # chrome reused across pages — $ref placements
  library/components/         # optional blocks for editor drag-drop
  locales/en.json, ar.json…   # theme translations
  pages/<pageId>/
    page.json                 # { "props": { … } }
    components/
      hero.tsx                # flat leaf: export const meta + function App()
      order.json              # built-in type placement (e.g. order form)
      product-shell/          # folder only when slots/ or children/ needed
        product-shell.tsx
        slots/<slotId>/<child>/
  dist/
    data.json                 # compiled TemplateData
    schema.json               # merged editor schema
    locales/*.json

Disk → JSON mapping

Shared placement syntax (edit once, place everywhere):

{ "$ref": "shared.header", "instanceId": "header_home", "props": { "sticky": true } }

At build time $ref placements are inlined into the dist — no $ref survives in data.json. (Kit $ref is a build-time copy; runtime type: "reference" + refId is a different, server-resolved mechanism.)

Commands

feeef template add page products
feeef template add component products grid --title "Product grid"
feeef template remove component products grid --yes

npm run build      # feeef template build → dist/
npm run check      # validate without writing
npm run dev        # feeef template dev → remote draft preview
npm run publish -- --apply

Prefer add/remove over hand-creating folders — they keep the manifest and starter meta correct.

Build guarantees

• Output always has a sections object per page (flat components/ normalizes to sections.main) — required by the merchant editor.
• TypeScript and imports are bundled per component into self-contained code strings (classic React.createElement, react external — see custom components).
• locales/*.json compile into data.i18n for local builds; on publish they are uploaded to the dedicated store_template_locales table instead.
• Rebuilds are deterministic: commit source, never hand-edit dist/data.json.

Preview

npm run dev pushes a draft to your bound store and opens https://{slug}.feeef.store/?preview={token} — the full shop (home → product → checkout) renders your draft while customers keep seeing the live theme. Mechanics and safety rules are covered in the CLI docs.

Theme conventions

Every published theme is expected to ship:

• design-system.md — the theme's own visual contract (tokens, spacing, motion, component chrome). Editors and AI assistants follow it for all visual decisions.
• Locales for every user-facing string via t() — not hardcoded copy.
• Currency symbols from store.configs.currencies[].symbol (e.g. دج), not ISO codes.
• Dark/light/system support riding the native CSS tokens.
• A floating order CTA on product pages that scrolls to the buy button.
• Feeef credit in the footer.

These conventions are enforced during marketplace review.