Legacy library standard

This standard describes how Chroma apps declare third-party legacy JavaScript (UMD/IIFE globals). It complements the Plugins, which covers ESM packages under plugins/<id>/.

Source of truth (monorepo): Chroma/cli/legacy-libs/registry.json (bundled with the Chroma CLI; copied to $CHROMA_HOME/legacy-libs/ on install).

First-party plugins (maintainers): plugins-registry.json sits beside the globals registry under Chroma/cli/legacy-libs/. It lists canonical workspace paths, build hints, and pinned versions for browser plugins (chroma-fs, chroma-style, …) — not UMD entries in libraries[]. The CLI release bundle copies it when present; npm run legacy-lib:list -- --plugins and refresh-version read it. Apps install plugins with chroma install and chroma.json → plugins[]; see the Plugins.

JSON Schema: legacy-lib-registry.schema.json

chroma.json schema (canonical): targ-apps-docs/public/schemas/chroma/chroma.schema.json in the monorepo (published at /schemas/chroma/chroma.schema.json); Chroma and Chroma-Linter do not ship a duplicate copy.

Goals

1. One id per library — stable slug (chartjs, dayjs) used in manifests, docs, and CI.
2. Pinned versions — registry entries record the semver of vendored/CDN artifacts.
3. Predictable loading — chromaJson.hooks.load tells tooling where to inject scripts.
4. CDN resilience — ordered cdn.primary + cdn.fallbacks without hand-maintaining URLs in every app.
5. Separation from plugins — no chroma.plugin.json; globals are optional and explicit.

Registry entry shape

Each object in libraries[] must include:

files[]

cdn

"cdn": {
  "primary": "https://cdn.jsdelivr.net/npm/dayjs@1.11.13/dayjs.min.js",
  "fallbacks": [
    "https://unpkg.com/dayjs@1.11.13/dayjs.min.js"
  ]
}

Tooling should try primary first, then each fallback in order. Apps may override with legacyLibraries[].url for a self-hosted mirror (see below).

chromaJson

Load hooks (chromaJson.hooks.load)

Dynamic apps typically use indexHtml:head or indexHtml:body-end so globals exist before bundle.js executes. Static apps should set staticBuild: "append-scripts" so chroma build minifies vendor files with the rest of the script list.

chroma.json — legacyLibraries

Optional top-level array on the app manifest (see chroma.schema.json):

"legacyLibraries": [
  {
    "id": "chartjs",
    "source": "vendor",
    "version": "4.4.1"
  },
  {
    "id": "dayjs",
    "source": "auto"
  }
]

Example with mixed sources:

{
  "$schema": "https://docs.targapps.xyz/schemas/chroma/chroma.schema.json",
  "name": "reports-dashboard",
  "mode": "dynamic",
  "entry": "index.html",
  "legacyLibraries": [
    { "id": "lodash", "source": "vendor" },
    { "id": "chartjs", "source": "cdn" }
  ],
  "build": {
    "jsEntry": "src/main.chr",
    "outfile": "bundle.js",
    "format": "esm",
    "minify": true
  }
}

From .chr code, read globals only after scripts load (e.g. on first render or after DOMContentLoaded):

const chart = globalThis.Chart;

Prefer wrapping globals in a small module under src/legacy/ when migrating toward ESM.

Vendoring workflow

1. Pick id from the registry (or add a new entry in Chroma/cli/legacy-libs/registry.json and bump registryVersion if semantics change).
2. Create paths listed in files[] under your app root (commonly vendor/<name>/).
3. Declare legacyLibraries in chroma.json.
4. Run chroma validate — manifest shape is schema-checked; file presence checks may be added in the CLI later.
5. For air-gapped deploys, use source: "vendor" only and commit vendored bytes.

Adding a new library to the registry

1. Edit Chroma/cli/legacy-libs/registry.json (validate with AJV against legacy-lib-registry.schema.json).
2. Choose an unused id and categories.
3. Pin version and mirror that version in cdn URLs.
4. Set chromaJson.global to the actual global (inspect the UMD build in a browser console if unsure).
5. Document breaking changes in notes and, when needed, add audit-<yyyy-mm>.mdx under this folder.
6. Regenerate the docs catalog: npm run legacy-libs:catalog (from the workspace root). CI may run node scripts/generate-legacy-libs-catalog.mjs --check to ensure catalog.mdx matches the registry.

Validation (local)

cd targ-apps-docs/public/schemas
npx --yes -p ajv-cli@5 -p ajv@8 ajv validate \
  -s chroma/legacy-lib-registry.schema.json \
  -d ../../../../Chroma/cli/legacy-libs/registry.json \
  --spec=draft2020

Relationship to other Chroma artifacts

Current registry entries (v1)

See the generated catalog and registry.json for CDN URLs, vendor paths, and hook metadata.