Targ Apps Docs
Chroma

Zed extension

Install the Chroma extension for the Zed editor to get .chr syntax highlighting, the Chroma linter and type diagnostics, completion, hover, go-to-definition, themes, file icons and snippets.

The Chroma extension for Zed (chroma, source folder Chroma-Zed) adds full editor support for Chroma apps: it recognizes .chr files, highlights them (including the Chroma API such as e, hookState, Show and For), reports errors in the same way as the linter, and ships two themes, a file icon theme and snippets. It is the Zed counterpart of the VS Code extension and uses the same rules.

In plain words: install the extension, open the folder that contains your app's chroma.json, and open any .chr file. Colors and the outline work right away; errors appear in the diagnostics panel (Ctrl+Shift+M) as you type.

What is included

PieceWhat it gives you
Language Chroma.chr files: highlighting, bracket matching and rainbow brackets, auto-indent, outline (functions, classes, exports, imports), comment toggling, text objects for Vim mode.
Language Chroma Manifestchroma.json, chroma-fs.json and chroma.plugin.json as JSON with Chroma key highlighting.
Language server chroma-lspDiagnostics, completion, hover and go-to-definition for .chr, and schema-driven completion, hover and validation for the manifests. See Diagnostics and Manifest completion.
ThemesChroma Dark and Chroma Light, in the Targ Apps palette (cream, terracotta and dark brown).
Icon themeChroma Icons: the Chroma mark for .chr, chroma.json, chroma-fs.json and chroma.plugin.json, plus icons for common file types and folders such as src, plugins and pkg.
Snippetscomp, e, state, effect, show, for, cva, router, screen and more for .chr files.

Install

The extension is not in the Zed extension store yet, so install it as a dev extension from the repository.

  1. Install Rust with rustup. Zed compiles the extension to WebAssembly and installs the wasm32-wasip2 target by itself when Rust comes from rustup.

  2. In the Chroma-Zed folder, make sure the grammar points at your checkout. Zed builds the grammar from a git commit, so commit the folder first, then run the rev script:

    cd Chroma-Zed
    git add -A && git commit -m "[a] feat: Chroma extension for Zed"
    npm install
    npm run rev -- --local   # writes the file:// URL of this checkout and HEAD into extension.toml
    git commit -am "[a] chore: pin the grammar"
  3. In Zed, run zed: install dev extension (or open Extensions and click Install Dev Extension) and select the Chroma-Zed folder.

  4. Open an app folder and a .chr file. To use the theme and icons, run theme selector: toggle and pick Chroma Dark or Chroma Light, then icon theme selector: toggle and pick Chroma Icons.

If something does not load, run zed: open log. For verbose output, quit Zed and start it from a terminal with zed --foreground.

The wasm of the extension and the language server are built from the files committed in Chroma-Zed. After you change grammar.js, the queries or the server, run npm run build, commit, and run npm run rev -- --local again.

Diagnostics and the language server

The language server is a Node.js process built on @chroma/linter. Zed runs it with its own managed Node.js, so you do not need to install Node. The server code is embedded in the extension. On first start the extension also installs the typescript npm package next to it, which the type checks need. If that download fails, everything except type checks keeps working and the server log says so.

SourceRule idsWhen
Syntax of .chrchroma/chr-syntaxAs you type
Type problems in .chrchroma/chr-type, chroma/chr-unresolved-import, chroma/cdn-types-unavailableA moment after you stop typing, only when the file has no syntax errors
Manifest schemachroma/schema, chroma/parse-error, chroma/schema-refAs you type in chroma.json, chroma-fs.json, chroma.plugin.json. The marker sits on the offending key; chroma/schema-ref (warning) marks a $schema that is not a Chroma schema.
Browser firstchroma/chr-node-api (info)Node.js APIs (process, Buffer, require, node: imports) used under src/. Only a note: Chroma apps run in the browser. Node code outside src/ is left alone.
Unused codechroma/chr-unused (hint)Unused imports and variables, faded like in React tooling. _name and e are exempt.
Project importschroma/chr-import-outside-root, chroma/chr-unresolved-import, chroma/chr-import-extensionAs you type in open files, and for every other .chr of the project from the index. See Imports and the project root.
Project ruleschroma/entry-missing, chroma/plugin-dir-missing, chroma/chr-route-missing, and the other linter project rulesOn open and on save

Completion, hover and go-to-definition work in .chr files, including for libraries imported from a CDN, whose TypeScript definitions are downloaded once into .chroma/types. See Web globals, Node globals, and CDN imports for how the definitions are found.

Imports and the project root

The project root is the folder that contains chroma.json. Every import is resolved inside it: a file can reach anything in the project, and nothing above it.

SpecifierResolves from
./x.chr, ../x.chrThe importing file
/src/x.chrThe project root
https://…, gsap, node:fsNot project files: left to the type checker

The language server checks every project import:

  • An import that climbs above the root is an error (chroma/chr-import-outside-root).
  • A missing file is an error (chroma/chr-unresolved-import) and suggests the closest file with that name: Did you mean "./components/Button.chr"?.
  • An import without its extension is a warning (chroma/chr-import-extension), because Chroma serves modules to the browser as they are and ./router would not load. The message gives the fixed path.

On the import string you also get go to definition (Ctrl+Click or F12), hover with the project path, and path completion (Ctrl+Space, or automatically after /) that lists the files and folders of the directory written so far and never offers anything above the root. Standing on a complete name, for example "../../lib/reveal-scope.chr|", lists every file of ../../lib/; typing narrows the list, and accepting an item replaces the whole path segment. Typing / completes from the project root.

Auto-import

Every export of the project is indexed, so any of them can be used without importing it by hand. Press Ctrl+Space while you type a name, for example scrollToSec, and the list includes scrollToSection with the file it comes from (../../lib/scroll-to-section.chr). Accepting it inserts the name and adds the import in the same edit:

  • If the file already imports from that module, the name joins the existing braces: import { e } from "../pkg/chroma.js" becomes import { e, For } from "../pkg/chroma.js".
  • Otherwise a new import line is added after the last import (or at the top).
  • A default export is imported with its own name, or with the file name in PascalCase (nav-links.chr becomes NavLinks).
  • Names already imported or declared in the file are not offered again, and nothing is offered inside strings, comments or after a ..

Auto-import covers every .chr file, the project's own .js and .mjs files, and the engine API in pkg/chroma.js (e, hookState, Show, For, cva…). It skips vendor/ and minified files. It works even when type checking is not available. Auto-import items sort after the names that are already in scope.

The project index

To know every file without opening it, the server keeps .chroma/index.json in the project root: all files (without node_modules, dist, build, .git or symlinks, so it never leaves the root), the resolved imports of each .chr, and the exports of every source file (name, or name:function / name:class for functions and classes, and default:… for default exports).

{
  "version": 1,
  "root": ".",
  "files": ["chroma.json", "src/App.chr", "src/router.chr"],
  "chr": ["src/App.chr", "src/router.chr"],
  "problems": 0,
  "exports": { "src/router.chr": ["router"], "src/lib/nav-links.chr": ["default:function", "NAV_LINKS"] },
  "imports": {
    "src/App.chr": [{ "specifier": "./router.chr", "status": "ok", "resolved": "src/router.chr", "line": 3 }]
  }
}

The index is not part of the app. Nothing imports it, chroma dev and chroma build do not read it, and .chroma/ has its own .gitignore. The server regenerates it when a file is created, deleted, renamed or changed (and on open and save), writes it only when its content changes, and uses it to report import problems of files that are not open. If the editor is not running, the same script works from a terminal:

node chroma-lsp.mjs --index path/to/project          # build once
node chroma-lsp.mjs --index path/to/project --watch  # keep it fresh

chroma-lsp.mjs is the bundle the extension writes to ~/.local/share/zed/extensions/work/chroma/chroma-lsp-<version>/, or server/dist/chroma-lsp.mjs in the Chroma-Zed repository.

Settings

Set these in your Zed settings.json (zed: open settings):

{
  "lsp": {
    "chroma-lsp": {
      "settings": {
        "types": {
          "enabled": true,
          "severity": "warning",
          "offline": false,
          "cacheDir": ""
        }
      }
    }
  }
}
SettingDefaultMeaning
types.enabledtrueTurn type checking, completion, hover and go-to-definition on or off.
types.severity"warning""error", "warning" or "off" for type problems. With "off" the language service is not started.
types.offlinefalseNever use the network. CDN definitions come only from the local cache.
types.cacheDir""Folder for downloaded .d.ts files. Empty uses .chroma/types in the project.
types.nodeApi"info""off" silences the Node.js notes in src/. Node modules and globals are always known and never an error.
types.unusedtruefalse turns off the faded hints for unused imports and variables.

To run your own build of the server instead of the embedded one, point Zed at it:

{
  "lsp": {
    "chroma-lsp": {
      "binary": { "path": "node", "arguments": ["/path/to/chroma-lsp.mjs", "--stdio"] }
    }
  }
}

Manifest completion and schema

Zed gives chroma.json, chroma-fs.json and chroma.plugin.json the Chroma Manifest language, so Zed's own JSON server (the one that reads $schema) is not attached to them. chroma-lsp does that job itself, from the schemas bundled in the extension (the same ones as docs.targapps.xyz/schemas):

You doYou get
Ctrl+Space on an empty line inside the objectThe keys of the schema at that level that are not there yet, with description and type. Accepting one writes "mode": "static" with the value as a snippet (static/dynamic as a choice, [], {}, true/false)
Ctrl+Space inside a key you are typingThe matching keys; accepting replaces only the key
Ctrl+Space after a colon, or inside the quotes of a valueAllowed values (enum), true/false, the default and the schema examples. In plugins it lists the plugin ids (chroma-style, chroma-seo, chroma-icons...)
Ctrl+Space in pluginOptionsThe plugins listed in plugins, then the options of the native plugins (chroma-style: src, include, colors...; chroma-seo: data, jsonLdFile, shellFile; chroma-icons: icons, output; chroma-blog: sourceDir, rss), which the schema leaves open
Hover on a keyIts description, type, allowed values, default and an example
`"$schema": ""`

$schema is honoured: the manifest is validated and completed against the schema it names. It can be a docs.targapps.xyz/schemas/... URL, another URL whose file name is a bundled schema, an absolute path, or a path relative to the manifest ("./my.schema.json", compiled on the fly). With no $schema the schema of the file name is used. A $schema that resolves to nothing is reported as a warning (chroma/schema-ref) and the bundled schema is used instead.

If you still want Zed's JSON server next to chroma-lsp (for example for schemas of other tools), enable both for the manifest language and map the schemas yourself:

{
  "languages": {
    "Chroma Manifest": { "language_servers": ["json-language-server", "chroma-lsp"] }
  },
  "lsp": {
    "json-language-server": {
      "settings": {
        "json": {
          "schemas": [
            { "fileMatch": ["chroma.json"], "url": "https://docs.targapps.xyz/schemas/chroma/chroma.schema.json" }
          ]
        }
      }
    }
  }
}

Highlighting

.chr is a JavaScript module with JSX, so the extension ships a tree-sitter grammar named chroma that extends tree-sitter-javascript. It is a separate grammar so it never interferes with Zed's own JavaScript support. Besides the usual JavaScript tokens, the highlights mark:

  • the element builder e(...) and the tag name in e("div", ...);
  • the Chroma runtime API: hookState, useEffect, useMemo, useRef, createRouter, cva, cx and the rest of pkg/chroma.js;
  • the built-in components Show, For and Fragment;
  • custom hooks (useSomething(...)), JSX tags and attributes, and import specifiers.

The themes color these through function.special and type.special. In another theme they fall back to function and type.

Themes and icons

Chroma Dark uses the dark brown background #16110e with terracotta keywords, and Chroma Light uses the cream background #faf9f5. Both come from one palette in scripts/gen-assets.mjs, which also generates the icon theme and its SVG files, so they stay consistent. After editing the palette, run npm run assets.

Tasks

The extension does not ship tasks. To run the Chroma CLI from Zed, add them to your project in .zed/tasks.json:

[
  { "label": "Chroma: dev", "command": "chroma dev", "use_new_terminal": true },
  { "label": "Chroma: build", "command": "chroma build" },
  { "label": "Chroma: validate", "command": "chroma validate" }
]

Run them with task: spawn.

Develop the extension

cd Chroma-Zed
npm install
npm run build        # grammar, themes and icons, language server bundle, extension wasm
npm test             # queries, real .chr files, theme schemas, language server over stdio
Folder or filePurpose
extension.tomlManifest: grammar, language server, ids
grammar.js, src/parser.c, src/scanner.cTree-sitter grammar (generated with npm run generate)
languages/chroma, languages/chroma-manifestconfig.toml and the tree-sitter queries
src/lib.rsRust extension that starts the language server
server/srcLanguage server source, bundled into server/dist by npm run build:server
themes, icon_themes, icons, snippetsThemes, icon theme, SVG icons and snippets
scripts/test-*.mjsTests

Every change to the extension bumps its version: npm run bump -- patch for fixes and tweaks, minor for new features, major for breaking changes. It updates extension.toml, Cargo.toml and package.json; then run npm run build:server && npm run build:wasm.

The server bundle needs Chroma-Linter built next to Chroma-Zed (npm run build there), or CHROMA_LINTER_DIR pointing at it. npm test compiles every query against the grammar, parses all .chr files in the workspace without errors, validates the themes against Zed's JSON schemas, and drives the server through diagnostics, hover, completion and definition.

Publish

To publish to the Zed extension store, push Chroma-Zed to GitHub, run npm run rev (without --local) so the grammar uses the GitHub URL, commit, and follow Zed's publishing guide to open a pull request on zed-industries/extensions. The repository is GPL-3.0-or-later, which Zed accepts.

Troubleshooting

SymptomFix
No completion, hover or diagnostics after rebuilding the dev extensionZed stops the language server when the extension reloads and does not always start it again for the open file. Run editor: restart language server, or close and reopen the .chr file. The language server menu in the status bar should list Chroma Language Server, and its log starts with chroma-lsp <version> started.
An import is reported as outside the project rootThe file is above the folder that has chroma.json. Move it inside the project, or move chroma.json up so the project root contains it.
A new file does not complete or resolveThe index refreshes within a fraction of a second of the file appearing. If your system limits file watchers, save any .chr file to refresh it.
.chr files open as plain textThe dev extension failed to load. Open zed: open log; a grammar error usually means rev in extension.toml is not a commit that contains src/parser.c. Run npm run rev -- --local.
No diagnostics at allCheck that the file is recognized as Chroma in the status bar, and look for chroma-lsp errors in dev: open language server logs.
Syntax errors but no type problemstypescript could not be installed (offline, or npm blocked). The language server log says semantic checks are unavailable. Connect once so the extension can install it.
Type problems for a CDN importThe definitions could not be downloaded. Set types.offline to false, or lower the severity with types.severity.
Manifest is highlighted as plain JSONThe file name must be exactly chroma.json, chroma-fs.json or chroma.plugin.json.

On this page