chroma add

Vendor UMD/global legacy libraries into a Chroma app — distinct from chroma install (engine and ~/.chroma plugins).

chroma add <lib-id> vendors a third-party UMD/global entry from Chroma/cli/legacy-libs/registry.json into the current app directory. Implementation: Chroma/cli/lib/chroma-add.mjs, invoked by chroma.sh / chroma.ps1.

Not the same as chroma install. chroma install sets up the Chroma engine under ~/.chroma, copies templates, and installs first-party plugins into $CHROMA_HOME/plugins/ (global CLI toolchain). chroma add is only for UMD/CDN globals (echarts, dayjs, lodash, …) in your project (vendor/, legacyLibraries[], index.html).

When to use which command

Goal	Command
Install or refresh the Chroma CLI, WASM engine, schemas, and bundled plugins under `~/.chroma`	`chroma install`
Scaffold from a template that already lists plugins in `chroma.json`	`chroma new` (templates under `$CHROMA_HOME/templates`)
Vendor a registry global id (UMD script + hooks) into an existing app	`chroma add <lib-id>`
Add `chroma-fs` via npm `file:` instead of copying plugins	`chroma fs init` / `chroma fs link`
Copy first-party plugins into `./plugins/`	`chroma install` then copy from `$CHROMA_HOME/plugins/`, or `sync-chroma-plugins.sh` in the monorepo

First-party plugins (chroma-fs, chroma-style, chroma-router, chroma-t2t) are not installed with chroma add. Maintainer sync metadata lives in Chroma/cli/legacy-libs/plugins-registry.json.

What `chroma add` does

For each UMD/global registry id (chartjs, dayjs, lodash, echarts, anime, lucide, …):

Vendor — downloads cdn.primary (or copies from Chroma/cli/legacy-libs/vendor/ mirror when present) into app paths listed in files[] (typically vendor/<id>/…).
chroma.json — appends or updates legacyLibraries[] with { "id", "source": "vendor", "version" }.
index.html — injects <script> / <link> tags per chromaJson.hooks.load, wrapped in  markers (re-run with --force to refresh).
Static mode — when hooks.staticBuild is append-scripts, merges script paths into build.scripts.

Usage

cd my-chroma-app
chroma add --list
chroma add dayjs
chroma add echarts --force
chroma add chartjs --dry-run

Flag	Description
`--list`	Print UMD/global registry ids, versions, and names (tab-separated)
`--force`	Overwrite vendored files and refresh manifest / HTML hooks
`--dry-run`	Print download, manifest, and HTML steps without writing
`--registry <path>`	Override `registry.json` location
`-h`, `--help`	Built-in help

Requires Node.js (same as chroma build). Run from a directory that contains chroma.json.

Registry resolution

The helper checks, in order:

--registry <path> or CHROMA_LEGACY_REGISTRY
$CHROMA_HOME/legacy-libs/registry.json (copied during chroma install)
Chroma/cli/legacy-libs/registry.json (bundled next to the CLI script in the monorepo)

Example `chroma.json` after `chroma add dayjs`

{
  "legacyLibraries": [
    {
      "id": "dayjs",
      "source": "vendor",
      "version": "1.11.13"
    }
  ]
}

See Standard for source: "cdn", auto, and url overrides without vendoring.

Catalog — all global ids and versions
Plugins — runtime loading and chroma.plugin.json
CLI reference — install, dev, build, validate

When to use which command

What chroma add does

Usage

Registry resolution

Example chroma.json after chroma add dayjs

Related

On this page

What `chroma add` does

Example `chroma.json` after `chroma add dayjs`