Add a theme

Run integration add theme with a lowercase kebab-case slug. It writes a blank theme — a defineTheme skeleton and its descriptor — into a folder named after the slug.

bash
npx astryx integration add theme ocean

text
theme contribution added
​
[ok] ocean
​
Declare theme root ./themes in astryx.integration.mjs.
​
- themes/ocean/oceanTheme.ts
- themes/ocean/oceanTheme.doc.mjs
- package.json
- astryx.integration.mjs

oceanTheme.ts exports oceanTheme, a defineTheme source. oceanTheme.doc.mjs describes it with type: 'theme', name, displayName, description, and maintained; theme list shows its name, description, and maintained. The command also declares ./themes/ocean and ./themes/ocean.css package exports. Every descriptor field is in astryx docs authoring.

The source and built outputs ship in your package. Build the source with theme build, then run integration verify before publishing. An app runs theme add --import to record and import the built module and stylesheets; plain theme add still copies source while that default is deprecated. See astryx docs cli/integrations/building-blocks/themes/use-a-theme-in-an-app.

To begin from an existing theme instead of a blank one, pass --from. It copies that theme as your starting point to diverge from — a fork, with no link back.

bash
npx astryx integration add theme ocean --from neutral

The copy keeps the packages the base theme uses, such as lucide-react for its icons: --from adds them to your dependencies, so an app that installs your package gets them too. Install your dependencies again before you build the theme.

Use --from when you want to change a lot. For a small change that should stay linked to a base theme, use extends instead (astryx docs cli/integrations/building-blocks/themes/define-the-theme).

A package can ship more than one theme. Run integration add theme once per slug; each theme gets its own folder and descriptor, and theme list shows them all.