Storefront templates
Build editable Feeef themes as documents, with Helium runtime guides, draft previews and marketplace releases.
A Feeef theme is a document describing pages, sections, component instances, editable props, slots and translations. Developers author TSX; the CLI builds TemplateData; merchants customize it in the visual editor. Feeef hosts the storefront.
Helium is the new Hono + Preact runtime, using isolated merchant rendering and browser
islands. Lithium is the existing Next.js runtime. Start new Helium work with --helium;
keep Lithium-specific examples scoped to that renderer and review compatibility when migrating.
Build with Helium
Runtime contract, schema v2, standard pages, previews and isolated rendering.
Create a template
Scaffold, edit a block, test a hosted draft and publish a release.
Hydration in Helium
Schedule interactive islands and keep verified static content as HTML.
Move an existing theme
Review dependencies, preserve content, verify routes and switch deliberately.
The contract
| Part | Role |
|---|---|
| Schema | Declares editor pages, component types and editable propsSchema |
| TemplateData | The merchant's tree of pages, sections and component instances |
| Editor | Changes props and placements without changing the source package |
| Runtime | Renders the document and supplies platform controls and page data |
| CLI | Builds source, uploads a hosted draft and publishes versioned releases |
Keep schema and data separate: schema describes controls; data contains their current values.
Custom code and propsSchema sit beside props, rather than inside merchant content.
Authoring layout
New themes use a main section. Flat pages/<id>/components/*.tsx files become its blocks.
A component gets a folder when it owns slots/ or children/. Shared chrome uses build-time
$ref placements; the library is the merchant's insertable component catalog.
The Helium starter includes home, products, category, product, cart, checkout, contact, thanks
and not-found pages. Use the generated manifest and schema.ts as the page contract. Legacy
Lithium guides may use different IDs, such as thank_you.
Develop, then apply
feeef template init my-theme --helium --store my-shop
cd my-theme
npm run check
npm run build
npm run devThe CLI defaults to the alpha API; select the API that owns the store before sign-in.
Helium drafts use {slug}.h.feeef.store. Draft preview uses real catalog data while the live
document stays installed. npm run publish -- --apply explicitly replaces the live install.