Building a NUMU V3 Theme

The four packages and their roles — never blur them:

1. Scaffold

npx @numueg/theme-cli init <theme-name>   # or: numu-theme init

The scaffold already includes: all required templates, the standard 5-color + 2-font settings_schema.json block (wired to --theme-* CSS vars), Header/Footer + ~15 sections, vite.config with numuTheme({ federate: true }), bilingual patterns.

Non-negotiable rule: component filename = schema section type. A section whose schema type is featured_collection lives in src/sections/featured_collection.tsx. The registry is built by filename convention; a mismatch = section silently never renders.

2. Dependencies

// package.json — the split matters
"dependencies":    { "@numueg/theme-kit": "^0.1.0" },          // inlined
"devDependencies": { "@numueg/theme-sdk": "^0.10.0",           // externalized at build
                     "@numueg/theme-plugin": "^0.6.0",
                     "@numueg/theme-cli": "^0.7.0" }

3. Settings access — theme-kit, never hand-rolled guards

Merchant settings arrive as untyped JSON. Do NOT write local asString/localized helpers (that was the pre-kit copy-paste era). Import from the kit:

import {
  localized,        // localized(locale, en, ar) — ar-aware picker
  asString, asNumber, asBool, asArray, asRecord,   // type guards w/ fallbacks
  asImageUrl, asImageAlt,                          // image-setting readers
  readBlocks, pickItems,                           // block-container readers
  formatMoney, centsToMajor,                       // money formatting
  asImageTransform, applyImageTransform,           // focal-point/crop transforms
} from "@numueg/theme-kit";

const title = asString(s.title) || localized(locale, "New arrivals", "وصل حديثاً");

If a helper is missing from the kit, add it TO the kit (PR + release), don't fork it locally.

4. SDK usage — what each new feature gives you for free

• Navigation: always <Link to="/products/foo"> from the SDK. Since 0.10 it soft-navigates (client-side transition, no reload/remount) when the host supports it and falls back to a full nav otherwise. Programmatic: requestNavigate(href). Never use next/link, window.location, or raw <a> for internal paths.
• Money: <Money amount={...} currency={order.currency}> or kit formatMoney. NEVER hand-divide /100 or hardcode "EGP"/"ج.م" — multi-currency is live. ⚠ Pitfall: variant.price.amount is cents; product.price is major units.
• Global sections: useSectionGroup("header") / "footer" returns the ordered instances from themeSettings.section_groups; render them through your own registry. Themes that do this render their chrome on EVERY route consistently.
• Template overrides: usePage().template carries product.<suffix> etc. The host resolves template_suffix (Shopify OS 2.0-style variants) — render whatever template key you're handed; never hardcode "the product template".
• Data: useCachedResource(key, fetcher) for theme-custom data (SWR-style dedup + cross-instance sync). Catalog basics come from useShop/useProduct/useCollection/ useProducts/useCart/useCustomer/useNavigation/useSearch.
• Variants: useVariantSelection(product) — it publishes the live picker axes to the selection registry so addItem labels cart lines ("Black, L") even for legacy products. Custom add-to-cart buttons: publishVariantSelection/readVariantSelection.
• Checkout/account: useCheckout, useShippingRates, useOrders, useCustomerAddresses, useReorder, useGiftCardBalance — themes own these UIs.
• Rich text from merchants: SDK <RichText> only (sanitizes). Never dangerouslySetInnerHTML.
• Entry: defineThemeEntry(ThemeRoot) — gives mount (client) + createApp (SSR string render). Both must work: SSR parity is validated.

5. i18n / RTL — bilingual is mandatory

Every user-facing string ships en + ar. Fixed chrome strings: const t = useT()-style via SDK useLocale, or kit localized(locale, en, ar). Merchant content: bilingual settings (heading_en/heading_ar or i18n maps) read with localized. Layout must survive dir="rtl" — use logical CSS properties (margin-inline-start, not margin-left).

6. Validate + dev loop

numu-theme dev        # local dev server against a store
numu-theme check      # schema/manifest validation (single-source: SDK /validation)
numu-theme lint       # section conventions
npm run build         # vite + plugin → dist/theme.js, import-map.json, manifest

Build output must show federate: true and the current sdk_compat_minor in dist/import-map.json, with react/@numueg/theme-sdk externalized (grep dist/theme.js for from"react" — it must be an import, not inlined source).

• The host gates on sdk_compat_minor: a bundle built against a NEWER SDK minor than the host runtime serves is refused with a clear error. Build against the published SDK version the storefront runtime serves.
• If the theme renders its own header/footer chrome via section groups, the manifest flag renders_global_sections (plugin ≥0.6.0 emits it) tells the host not to double-render fallback chrome.

7. Ship

1. Bump theme.json version — the marketplace seed is idempotent by slug+version; an unbumped version silently overwrites in place and merchants never see an update.
2. Commit to V3-themes on a feature branch → PR → merge to main (triggers the R2 deploy + registry seed for test + prod).
3. Stores are never auto-switched — merchants adopt the new version from the hub.

Pitfalls checklist (each one has bitten us)

• filename = schema type for every section
• no local guard helpers — kit imports only
• no /100, no hardcoded currency strings; <Money currency={...}> everywhere
• variant.price.amount = cents, product.price = major
• SDK <Link> for ALL internal nav (soft nav is free; raw <a> forfeits it)
• header/footer read from useSectionGroup, not hardcoded
• render page.template as handed (template overrides)
• bilingual en/ar + RTL-safe CSS on every section
• <RichText> for merchant HTML
• SSR parity: createApp renders without window/document access at module top level
• theme.json version bumped before merge
• built against the SDK minor the host runtime currently serves