Build the theme
What a theme is
Theme anatomy
theme.json, billing.json, icon.svg and the Nuxt app — the four things a theme is made of.
The layer chain
your-theme → @revenexx/cover-theme → @revenexx/cover, and what each layer contributes.
Overriding the base layer
File-path shadowing and the deep-import map — replace any component without forking.
Service modes
Why the storefront runs locally with no credentials, and how you flip one domain to live data.
Building it
Design tokens
Tailwind 4, the palette, the theme presets, and branding per tenant without a rebuild.
Local development
The dev loop, the NUXT_* variables, and the rootId the visual editor depends on.
Frameworks
The fifteen frameworks the platform builds, and how the adapter is detected.
Rendering
SSR versus static — what each gives you, and per-framework configuration.
A theme is a Nuxt 4 application plus a manifest. It is not a fork of a storefront and not a config file: it's a real app that extends a published base layer, inherits a working shop, and overrides whatever the customer's brand and process require.
That shape is what makes the work tractable. You don't own the catalog plumbing, the cart state machine, the checkout orchestration, or the account area — those arrive from the layer. You own the parts that are specific to this customer.
The four things a theme is
| Part | File | What it does |
|---|---|---|
| The manifest | theme.json | Tells the platform this is a theme, how to build it, what it needs, and which blocks editors can use. |
| The listing | billing.json | Marketplace pricing and support contacts. Pricing only. |
| The icon | icon.svg | Shown in Cockpit and the Marketplace. |
| The app | a Nuxt 4 project | The actual storefront — pages, components, blocks, server routes. |
Details in Theme anatomy.
The one thing to internalise first
Every commerce and pages domain in the theme resolves through a service key, and in development every key defaults to mock. A freshly cloned theme runs a full shop — catalog, cart, checkout — with no API key, no tenant, and no environment variables. Production flips the keys to api.
If you read one page in this group before writing code, read Service modes.
Where to go next
- Theme anatomy — the manifest field by field, and why versions are immutable.
- The layer chain — which of the two base layers to extend.
- Overriding the base layer — replace a component by putting a file at the same path.
- Service modes — mock to live, one domain at a time.
- Design tokens — brand it.
- Local development — the dev loop and the environment variables.
- Frameworks and Rendering — for sites that aren't commerce storefronts.
- Build your first theme — the hands-on tutorial.