chroma.json and schemas

chroma.json is the manifest the CLI reads for dev, build, and validate, and the file the browser plugin loader reads at runtime. Its shape is described by JSON Schema draft 2020-12 files published on this site.

Schema files

All schemas live under /schemas/chroma/ and are the canonical source. The aliases under /schemas/targ-apps/ exist for apps in the Targ-Apps suite; each alias references the same rules, so either URL validates a chroma.json.

Examples for each are in /schemas/chroma/examples/. Plugin-specific formats are under /schemas/chroma-plugins/.

Typical dynamic manifest

This is exactly what chroma new <name> --template dynamic generates (the standard template is the same apart from name):

{
  "$schema": "https://docs.targapps.xyz/schemas/chroma/chroma.schema.json",
  "name": "chroma-dynamic-app",
  "mode": "dynamic",
  "plugins": ["chroma-fs", "chroma-router", "chroma-style"],
  "entry": "index.html",
  "outDir": "dist",
  "engine": { "vendorDir": "pkg", "rebuildWasm": true },
  "build": { "jsEntry": "src/main.chr", "outfile": "bundle.js", "format": "esm", "minify": true, "sourcemap": true },
  "package": { "zip": true },
  "dev": { "port": 5173, "desktop": true }
}

Two defaults to know about:

• dev.desktop: true makes chroma dev open Chroma Desktop. Pass --no-desktop or set it to false to stay in the browser. This affects development host only; it does not add a second production build target (Runtime modes).
• engine.rebuildWasm: true makes chroma build recompile the engine, which needs a source-checkout install. Set it to false to build against the pkg/ already in your project.

The plugins array is copied into every chroma build output. Removing a plugin changes what ships in dist/, not which runtime mode you choose at deploy time. Host-specific plugin behavior (for example Chroma-Fs IndexedDB vs the Desktop filesystem bridge) is documented under Runtime modes and Plugins.

Only static and dynamic are valid mode values. standard is a template name, not a mode.

Field reference

Three programs read chroma.json, and they do not agree on the full field list. In the table, Schema is whether chroma.schema.json accepts the field, CLI is whether chroma dev, chroma build, chroma new, or chroma add read it, and Linter is whether @chroma/linter (and the VS Code extension) reads it beyond schema validation. "Schema only" means the field is accepted and documented but nothing acts on it.

Fields the schema rejects

The schema sets additionalProperties: false on the root and on engine, build, package, dev, and every legacyLibraries item, so any key not in the table above fails schema validation. Four keys are read by the linter anyway:

So a manifest that uses any of these gets chroma/schema errors from the linter next to the linter's own diagnostics, and chroma validate fails at its schema step (it exits before the structural checks). To keep chroma validate clean, leave them out; the linter infers .chr mode on its own when build.jsEntry ends in .chr or src/ contains a .chr file.

How the CLI finds a key

On macOS and Linux the CLI looks up each key by name at any depth in the file (with jq, or a text search when jq is missing), so a key name that appears twice, such as name or scripts, can resolve to the wrong one. On Windows (chroma.ps1) the CLI reads the exact paths shown above (engine.vendorDir, build.jsEntry, dev.port, and so on). Keep key names unique and use the paths in the table.

Validate

Add $schema as the first key so VS Code and other editors show completions and errors:

{
  "$schema": "https://docs.targapps.xyz/schemas/chroma/chroma.schema.json",
  "name": "my-app",
  "mode": "dynamic"
}

Then check the project from the terminal:

chroma validate              # schema + structure
chroma validate --no-schema  # structure only, works offline

chroma validate, the linter, and the schema check different things; the Linter page compares them. Flags and where the CLI looks for the schema catalog are in chroma validate. On Windows, chroma validate runs the structural checks only.

Common validation errors

Related

• Runtime modes — Portable (web) vs Executable (Desktop); manifest fields that affect dev host only
• CLI — validate, dev, build, and the compile pipeline
• Templates — default dev.desktop and plugins per template