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
| Piece | What 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 Manifest | chroma.json, chroma-fs.json and chroma.plugin.json as JSON with Chroma key highlighting. |
Language server chroma-lsp | Diagnostics, completion, hover and go-to-definition for .chr, and schema-driven completion, hover and validation for the manifests. See Diagnostics and Manifest completion. |
| Themes | Chroma Dark and Chroma Light, in the Targ Apps palette (cream, terracotta and dark brown). |
| Icon theme | Chroma 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. |
| Snippets | comp, 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.
-
Install Rust with rustup. Zed compiles the extension to WebAssembly and installs the
wasm32-wasip2target by itself when Rust comes from rustup. -
In the
Chroma-Zedfolder, 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" -
In Zed, run
zed: install dev extension(or open Extensions and click Install Dev Extension) and select theChroma-Zedfolder. -
Open an app folder and a
.chrfile. To use the theme and icons, runtheme selector: toggleand pickChroma DarkorChroma Light, thenicon theme selector: toggleand pickChroma 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.
| Source | Rule ids | When |
|---|---|---|
Syntax of .chr | chroma/chr-syntax | As you type |
Type problems in .chr | chroma/chr-type, chroma/chr-unresolved-import, chroma/cdn-types-unavailable | A moment after you stop typing, only when the file has no syntax errors |
| Manifest schema | chroma/schema, chroma/parse-error, chroma/schema-ref | As 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 first | chroma/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 code | chroma/chr-unused (hint) | Unused imports and variables, faded like in React tooling. _name and e are exempt. |
| Project imports | chroma/chr-import-outside-root, chroma/chr-unresolved-import, chroma/chr-import-extension | As you type in open files, and for every other .chr of the project from the index. See Imports and the project root. |
| Project rules | chroma/entry-missing, chroma/plugin-dir-missing, chroma/chr-route-missing, and the other linter project rules | On 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.
| Specifier | Resolves from |
|---|---|
./x.chr, ../x.chr | The importing file |
/src/x.chr | The project root |
https://…, gsap, node:fs | Not 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./routerwould 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"becomesimport { e, For } from "../pkg/chroma.js". - Otherwise a new
importline 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.chrbecomesNavLinks). - 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 freshchroma-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": ""
}
}
}
}
}| Setting | Default | Meaning |
|---|---|---|
types.enabled | true | Turn 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.offline | false | Never 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.unused | true | false 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 do | You get |
|---|---|
Ctrl+Space on an empty line inside the object | The 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 typing | The matching keys; accepting replaces only the key |
Ctrl+Space after a colon, or inside the quotes of a value | Allowed 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 pluginOptions | The 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 key | Its 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 ine("div", ...); - the Chroma runtime API:
hookState,useEffect,useMemo,useRef,createRouter,cva,cxand the rest ofpkg/chroma.js; - the built-in components
Show,ForandFragment; - 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 file | Purpose |
|---|---|
extension.toml | Manifest: grammar, language server, ids |
grammar.js, src/parser.c, src/scanner.c | Tree-sitter grammar (generated with npm run generate) |
languages/chroma, languages/chroma-manifest | config.toml and the tree-sitter queries |
src/lib.rs | Rust extension that starts the language server |
server/src | Language server source, bundled into server/dist by npm run build:server |
themes, icon_themes, icons, snippets | Themes, icon theme, SVG icons and snippets |
scripts/test-*.mjs | Tests |
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
| Symptom | Fix |
|---|---|
| No completion, hover or diagnostics after rebuilding the dev extension | Zed 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 root | The 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 resolve | The 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 text | The 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 all | Check 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 problems | typescript 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 import | The definitions could not be downloaded. Set types.offline to false, or lower the severity with types.severity. |
| Manifest is highlighted as plain JSON | The file name must be exactly chroma.json, chroma-fs.json or chroma.plugin.json. |
VS Code extension
Install the Chroma extension to get chroma.json, plugin manifest, and .chr diagnostics, completion, hover, and CDN type support in VS Code, Cursor, and VSCodium.
Architecture
How Chroma is structured - what runs in WebAssembly, where the JavaScript boundary is, and how a state change reaches the DOM.