Move a theme to Helium
Review a Lithium theme, port its blocks and routes, and verify a Helium release without replacing the live install during development.
Start a Helium project and move the theme's design and content into it. Changing only
runtime and schemaVersion does not port code, register routes or move a domain.
Keep the existing live release available while you verify the new draft.
Inventory the existing theme
| Area | Review |
|---|---|
| Source and content | Page IDs, instance IDs, defaults, merchant edits, shared/library placements |
| Dependencies | Next.js imports, React packages, Node APIs, render-time network or browser access |
| Interaction | Menus, cart, variant/offer/add-on pickers, gallery, forms, effects and pixels |
| Routing | Product links, categories, cart, checkout, thanks, not-found and canonical/custom host |
| Presentation | Brand tokens, Arabic/RTL, translations, fonts, responsive images and layout stability |
Preserve the merchant's edited content explicitly. A new starter contains defaults; it does not automatically merge edits from the installed template. Keep a copy of the current source and release identifier before porting.
Scaffold and port in small pieces
feeef template init my-helium-theme --helium --store my-shop
cd my-helium-theme
npm run check
npm run build
npm run devSelect the API that owns the store before sign-in. The CLI defaults to alpha; production
stores use feeef config set apiUrl https://api.feeef.org/v1 followed by feeef signin.
Keep the generated manifest's runtime: "helium" and schemaVersion: 2. Port shared CSS
and simple content first, then product and shopping controls. Use flat TSX metadata and
separate slots so the merchant retains editor controls. Keep corresponding instance identities
stable where the existing document relies on them.
Prefer the supplied Helium scope primitives. Remove Next.js server assumptions and Node built-ins from render code. Preact supports the supplied React-style authoring surface; arbitrary npm packages require testing in both isolated SSR and the browser.
Confirm routes and hydration
Use the starter's standard page IDs, including thanks for /thanks, and align the manifest,
schema.ts and folders. Review old thank_you conventions, custom landing routes and every
internal product/category link. Verify missing products and unknown URLs too.
Custom components hydrate by default. Keep shopping controls interactive. Mark only verified
static CSS, content and footer blocks as hydrate: "never"; see the
hydration reference. Review provider/slot dependencies
before changing wrapper behavior.
Verify the hosted draft
npm run check
npm run build
npm run check:perf
npm test
npm run devLocal smoke checks do not reproduce QuickJS or browser behavior. On the hosted draft, verify:
- Every standard route, empty state and not-found state, in supported languages and RTL.
- First touch and keyboard navigation, galleries, selectors, cart totals and checkout.
- Merchant-editable props and slots after moving or hiding blocks in the editor.
- Responsive images, visible LCP content, font loading, layout shifts and console errors.
- Slug host, exact custom-domain mapping, canonical URLs and the deployment's DNS/TLS setup.
Drafts use real catalog data; test checkout with a designated development store. Record browser performance separately from origin throughput and RSS.
Release and switch deliberately
Publish a versioned release after preview verification. --apply installs it on the linked
store; it changes the document customers receive. Hosting/domain routing must also target
Helium. Neither a manifest edit nor a successful publish switches that infrastructure.
Record the prior template/release and host configuration so you can restore the known install if verification fails. Recheck the public shop without a preview cookie after applying the release, including a real custom host where configured.
See Develop and publish for release semantics and Helium runtime for the authoring contract.