🗂️ Themes overview

A NUMU theme is the whole storefront a shopper sees: every page, section and block, written in React and TypeScript. You build it on your machine, the merchant installs it from the theme marketplace and customizes it in the theme editor, and NUMU serves it on their store — on their subdomain or their own domain.

You never touch the platform's code. The storefront host handles routing, server rendering and loading each page's data; your theme decides what all of it looks like, checkout and customer account pages included.

Start here

From numu-theme init to a live store, step by step.

Theme SDK

Hooks and components for products, cart, checkout and accounts.

CLI + Vite plugin

Scaffold, preview, lint, build and publish from your terminal.

Theme engine

How the storefront loads and renders your bundle.

The toolchain

Four packages, each with one job:

Package	What it does	How your theme gets it
`@numueg/theme-cli`	The `numu-theme` command: scaffold, dev server, check, lint, build, push, submit	Dev dependency
`@numueg/theme-plugin`	The Vite plugin that builds `dist/theme.js`, the manifest and the import map	`numuTheme()` in `vite.config.ts`
`@numueg/theme-sdk`	React hooks and components: `useCart`, `useProduct`, `<Money>`, `<Link>`, `<RichText>` and more	Provided by the storefront at runtime — never bundled
`@numueg/theme-kit`	Small helpers with no React in them: settings readers, money formatting, image transforms	Bundled into your theme

How a theme gets to a store

Scaffold

numu-theme init my-theme creates a working theme: pages, a hero section, a block, the settings schema and English and Arabic locales.

Build it locally

numu-theme dev serves your theme with hot reload against sample data. Point your own test store at the dev server to preview it inside the real theme editor.

Check it

numu-theme check validates theme.json, schemas and locales. numu-theme lint runs the static rules; --strict turns warnings into errors for CI.

Push and install on your test store

numu-theme push uploads the build to your developer sandbox — only you can see it. numu-theme install puts it on your test store so you can try it with real data.

Submit for review

numu-theme submit sends a version to the NUMU team. We review it before it is listed.

Merchants install it

Once approved the theme is public in the marketplace. Merchants install it, customize it in the theme editor and publish. Stores are never switched to a new version automatically — each merchant chooses when to update.

Rules every theme follows

Bilingual and right-to-left. Every string a shopper reads ships in English and Arabic, and layouts use logical CSS (margin-inline-start, not margin-left) so they work in both directions.

Money comes from the store. Stores sell in more than one currency. Format prices with <Money> or formatMoney — never divide by 100 or hardcode a currency.

Internal links use the SDK's <Link>, so navigation stays inside the storefront without a full page reload.

Merchant HTML goes through <RichText>, which sanitises it.

A section's file name matches its schema type. A section with type featured_collection lives in src/sections/featured_collection.tsx; a mismatch means it never renders.

Server rendering must work. Nothing touches window or document at module load.

Where to go next

New to NUMU themes: Start here.

Looking for a hook or component: Theme SDK, then Hooks and Components.

Setting up the build: CLI + Vite plugin.

Curious what data each page receives: Page data contract.

🗂️ Themes overview

The toolchain#

How a theme gets to a store#

Rules every theme follows#

Where to go next#

The toolchain

How a theme gets to a store

Rules every theme follows

Where to go next