CLI overview

The two repos that own a theme developer's local toolchain.

`numu-theme` (CLI)

numu-theme init <name>             # scaffold a fresh theme
numu-theme dev [--watch]           # local dev server with HMR
numu-theme check                   # validate theme.json + schemas
numu-theme lint [--strict] [--json] [--rules id1,id2]
numu-theme build                   # produce dist/
numu-theme push                    # upload dist/ to your dev sandbox
numu-theme submit                  # submit dist/ to the marketplace for review
numu-theme install <theme-id>      # install a published theme into your test store
numu-theme login                   # marketplace auth
numu-theme status                  # current login + active theme + build status
numu-theme doctor                  # diagnose common setup issues
numu-theme add-section <name>      # scaffold a new section (+ optional --from-library)
numu-theme add-block <section> <name>
numu-theme pull <theme-id>         # download published theme source
numu-theme delete <theme-id>       # soft-delete a draft / unpublish

Detailed command reference: CLI Commands.

`@numueg/theme-plugin` (Vite plugin)

Repo: numu-theme-plugin. Used in each theme's vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import numuTheme from "@numueg/theme-plugin";

export default defineConfig({
  plugins: [react(), numuTheme()],
});

What the plugin does:

Contract validation — checks src/main.tsx exports mount; checks React/SDK are externalized

Schema codegen — reads schemas/sections/*.json → writes typed declarations to src/__generated__/sections.d.ts

Dev-server middleware — serves /theme.js, /theme.css, /sections.json so the customizer can load your local build

Federation externals — auto-injects react, react-dom, @numueg/theme-sdk into rollupOptions.external

Asset pipeline — content-hashes assets/* and emits a manifest

Manifest emission — writes dist/manifest.json summarizing the bundle

Detailed plugin reference: Vite Plugin.

How they fit

┌────────────────────────────────────────────────────────────┐
│ theme repo                                                  │
│                                                             │
│  ┌───────────────┐                                         │
│  │  CLI commands │  ← high-level UX                        │
│  │  init, dev,   │                                         │
│  │  build, lint, │                                         │
│  │  submit, …    │                                         │
│  └───────┬───────┘                                         │
│          │ spawns Vite with plugin                         │
│          ▼                                                  │
│  ┌───────────────┐                                         │
│  │ Vite + plugin │  ← low-level build pipeline             │
│  │  contract,    │                                         │
│  │  codegen,     │                                         │
│  │  externals,   │                                         │
│  │  assets       │                                         │
│  └───────┬───────┘                                         │
│          │                                                  │
│          ▼                                                  │
│       dist/                                                 │
│         theme.js, theme.css, manifest.json                  │
└────────────────────────────────────────────────────────────┘

You only directly invoke the CLI. The plugin is implicit — numu-theme init scaffolds a vite.config.ts with it pre-wired.

Installing the CLI

Two options:

Global (recommended for daily use)

Per-project via `npx`

While the CLI is pre-publish, install from source:

Bundled section library

numu-theme add-section --from-library <slug> clones a production-grade section into your theme. Current entries (15):

hero-with-cta              announcement-bar
featured-products          countdown-timer
image-with-text            featured-blog-posts
newsletter-signup          contact-map
multi-column               collection-list
testimonials               video-embed
faq-accordion              rich-text
logo-cloud

--list prints the catalog. Detailed reference: Section Library.

Lint rules

numu-theme lint runs 10 static-analysis checks:

id	What it catches
`manifest-required-fields`	id/name/version/author on `theme.json`
`schema-registry-sync`	preset sections ↔ schema files
`locale-parity`	missing keys in non-default locales
`preset-schema-conformance`	preset settings only use schema-declared ids
`unused-settings`	settings_schema entries no theme reads
`img-missing-alt`	`<img>` tags missing alt
`hardcoded-text`	3+-word JSX text not behind `t()`
`inline-color-literal`	hex/rgb literals in style props
`forbidden-script-tag`	`<script>` in component sources
`use-app-no-availability-check`	`useApp()` callers without `.available` branch

Flags: --strict (warnings → errors), --json (machine-readable), --rules id1,id2,... (subset).

Detailed reference: Lint Rules.

numu-theme (CLI)#

@numueg/theme-plugin (Vite plugin)#

How they fit#

Installing the CLI#

Global (recommended for daily use)#

Per-project via npx#

Bundled section library#

Lint rules#