Linter

The Chroma linter (@chroma/linter) validates your project manifests against the published JSON Schemas, then runs extra project rules: plugin folders, entry files, semver, and the .chr source layout.

Which tool should I use?

chroma validate is built into the CLI. chroma-lint and the extension cover more rules: plugin manifests and versions, .chr layout, and the routes, source, lint, and build.chrEntry keys that chroma validate ignores and the schema rejects (see chroma.json).

Run it

From a Chroma app directory (the one with chroma.json):

npx chroma-lint --project .

Install the CLI from the @chroma/linter package, or run its bin/chroma-lint.mjs directly.

Set CHROMA_SCHEMAS_DIR if the linter cannot find the schemas (for example, when the package is copied elsewhere). The exit code is 1 when any error-severity diagnostic exists; warnings do not fail the command.

# JSON output for CI
npx chroma-lint --project . --json

What is validated

Common problems

Schema errors use the code chroma/schema; open the schema named in $schema for the exact definition.

A minimal valid dynamic manifest:

{
  "$schema": "https://docs.targapps.xyz/schemas/chroma/chroma.schema.json",
  "name": "my-app",
  "mode": "dynamic",
  "entry": "index.html",
  "outDir": "dist",
  "engine": { "vendorDir": "pkg", "rebuildWasm": false },
  "build": {
    "jsEntry": "src/main.chr",
    "outfile": "bundle.js",
    "format": "esm"
  }
}

Project rules

The rule ids are exported as RULE_IDS from @chroma/linter. The core rules are:

.chr mode

The .chr rules run when lint.chrSource is true, or when it is not set to false and any of these is true:

• source.format is "chr"
• build.jsEntry ends with .chr
• build.chrEntry is set
• at least one .chr file exists under src/

lint.chrOnlySeverity: "warning" downgrades the extension rules (chr-only-extension, and chr-route-extension for jsEntry and routes) from error to warning. Of these keys, the schema accepts none (source, lint, build.chrEntry), so setting them also produces a chroma/schema error. Rely on the automatic detection instead: a build.jsEntry ending in .chr or any .chr file under src/ turns the rules on. Projects with only src/**/*.js skip these rules.

Use it from code

import { lintChromaProject, toLspDiagnostics, RULE_IDS } from "@chroma/linter";

const result = lintChromaProject({ projectRoot: "/path/to/app" });
// result.diagnostics: file paths, 0-based ranges, code, severity
const lsp = toLspDiagnostics(result.diagnostics);

Router and routes rules

The first three rules apply only to projects that use the multi-page router layout (src/lib/router.{chr,js} with src/pages/, or logic/router.{chr,js} with pages/). chroma-finance/chroma-routes is different: it runs for every project whose chroma.json has a routes key, in or out of .chr mode.

To add a page: create src/pages/MyPage.chr, import it in src/lib/router.chr, add it to the routes map, and run Chroma: Lint Project.