Helium runtime

Helium is Feeef's Hono + Preact storefront runtime. You ship a TemplateData document, not an application server. The CLI compiles your TSX, metadata, slots and translations; the merchant edits the resulting document in the visual editor.

Lithium is the existing Next.js runtime. Its documents and packages need a compatibility review before moving to Helium.

Start a theme

Use Node 18+ for the CLI:

npm install -g @feeef.dev/cli
feeef signin
feeef template init my-theme --helium --store my-shop
cd my-theme
npm run check
npm run build
npm run dev

The CLI defaults to https://api.alpha.feeef.org/v1. For a production store, select feeef config set apiUrl https://api.feeef.org/v1 before signing in. Authentication and preview must use the API that owns the store.

A Helium draft opens on https://{slug}.h.feeef.store/?preview=…. The preview uses real catalog data. Use a designated development store when testing checkout. Applying a release is separate: npm run publish -- --apply changes the live install.

Compatibility fields

Keep these fields in feeef.template.json; the build carries them into dist/data.json:

{
  "runtime": "helium",
  "schemaVersion": 2
}

These are fields to retain in your existing manifest, not a complete replacement manifest. Helium accepts schema v2 documents; an incompatible document uses its default template. Keep both fields consistent so CLI routing and authoring checks agree. The marker does not move an existing domain to Helium or translate a Lithium theme.

Source layout

feeef.template.json
schema.ts
pages/<page>/components/*.tsx
shared/components/*.tsx
library/components/*.tsx
locales/*.json
types/feeef-live-scope.d.ts
docs/24-HELIUM-RUNTIME.md

Use flat TSX files with export const meta and function App(). Use a component folder only when it owns slots/ or children/. Reuse shared chrome with build-time $ref placements. Keep instance IDs stable when editing a theme the merchant already customized.

The starter includes home, products, category, product, cart, checkout, contact, thanks and not_found. Keep page IDs aligned between the manifest, schema.ts and the source folders. Existing Lithium examples may use thank_you; use the Helium starter's thanks convention.

Server rendering contract

Each executed merchant SSR job gets a fresh QuickJS runtime inside a bounded worker pool. The guest receives the public store/product/page data it needs. Node globals, filesystem, network and a runtime module loader are unavailable. Rendering has resource and execution limits; an infinite loop or oversized theme must not block the server indefinitely.

Use seeds such as useSlotContext("homeProducts") for synchronous rendering. Browser requests and browser APIs belong in effects or handlers, with hydration enabled. Imports belong at module scope and are bundled by the CLI. An import compiling successfully does not establish that its package can run in the Helium sandbox or Preact browser environment.

Use the supplied scope primitives for platform behavior: AppBar, OrderForm, ProductCatalog, ImageViewer, ProductVariants, ProductOffers and ProductAddons. Treat arbitrary React/Next.js dependencies as migration work, rather than assuming compatibility.

Browser behavior and caching

Custom components hydrate by default. Set meta.hydrate when you need an explicit schedule; use never only for verified static blocks. See the hydration contract.

Public render results can be reused briefly when the entire input snapshot matches. Drafts, previews and thank-you pages bypass the origin render-result cache. Render public content on the server; keep shopper-specific state in the browser and use supported checkout controls. Changing page data changes the cache key.

Custom domains must resolve through an explicit store-domain mapping and the deployment's DNS/TLS configuration. A custom host is not interpreted as a store slug by stripping its first label. Confirm the canonical host and store association before release.

Verify a release

npm run check
npm run build
npm run check:perf
npm test
npm run dev

The local smoke check renders components in its local environment; it does not reproduce QuickJS isolation. Use the hosted draft to verify every route, console errors, touch and keyboard navigation, pickers, gallery, cart totals, checkout and translations. Check a custom domain separately where configured.

The performance guide separates origin tests from browser budgets. The migration guide covers existing themes.