@themvora/cli
`themvora add`
Prerequisites
- Node.js 22+
- A project that
themvora initalready integrated
Add a theme source to a project init already set up.
themvora add preset mint
themvora add brand apple
themvora add seed "#6366f1" --family indigoSynopsis — Add a theme source to an existing project
Usage:
themvora add <preset|brand|seed> <value> [options]| Argument | Description |
|---|---|
<kind> | The source kind to add. |
<value> | The preset id, brand id, or seed colour. |
Options
| Option | Description | Default |
|---|---|---|
--dir <path> | Project directory. Defaults to the current directory. | — |
--family <name> | Theme family name, for a seed source. | — |
--style <name> | Generation style, for a seed source. Run themvora list styles for the available values. | — |
--plan | Print what would happen and exit. Never writes. | — |
--dry-run | Print the plan and exit. Never writes. | — |
--force | Replace the registry even when it was not generated by Themvora. | — |
--json | Emit the plan or the report as JSON on stdout. | — |
--quiet | Suppress progress output. | — |
Exit codes
| Code | Meaning |
|---|---|
0 | the registry was updated, or already had the source |
1 | command/runtime error, or a registry that cannot be extended |
2 | usage/argument error, or no Themvora registry |
Examples
themvora add preset mint
themvora add brand apple
themvora add seed "#6366f1" --family indigo
themvora add preset iris --dir ./my-app
themvora add preset iris --plan<!-- cli-command:generated:end -->Generated from
packages/cli/src/command-schema.json— the same contractthemvora --helprenders.
How it works
init writes a theme registry and records the sources it was built from in a
machine-readable line in that file:
/**
* Themvora application configuration.
*
* Generated by `themvora init`.
* …
* Source: preset mint.
* themvora:sources: [{"kind":"preset","id":"mint"}]
*/add decodes that list, appends its own source, resolves everything through the
same source resolver init uses, and regenerates the file with the same
renderer. Nothing is parsed back out of the TypeScript — the alternative would
break the moment a formatter reformatted the file.
That also means add is exactly as safe as init:
- Idempotent. Adding a source the registry already has reports
Already present — nothing changedand writes nothing. - Non-destructive. The file is regenerated only when it carries Themvora's generated header. A registry you maintain by hand is never rewritten.
- Stable defaults. Adding a source never changes the theme the app opens with — the first source's default stays the default.
Where the themes go
| Project | Registry file |
|---|---|
| React, Vue, Svelte, Solid (Vite) | theme.config.ts |
| Next.js App Router | themvora.themes.ts |
The file is the single declaration the integration reads, so nothing else has to change. Restart the dev server and the new themes are selectable.
Working with an existing project
add uses --dir rather than a positional, because both positionals name the
source:
themvora add preset iris --dir ./my-app
themvora add brand github --dir ./packages/webPreviewing
themvora add preset iris --plan
themvora add preset iris --dry-run --jsonBoth print what would change and write nothing.
When it refuses
add stops rather than guessing in three cases, and each says what to do:
- No registry. The project has not been integrated — run
themvora init. - A hand-written registry. The file exists but was not generated by Themvora,
so
addwill not rewrite it. - A registry with no source record. The file predates the source line. Re-run
themvora initto regenerate it, then add the source again.