Targ Apps Docs
Chroma

Quick start

Install the Chroma CLI, scaffold an app, run it, edit it, and build it for production.

This page takes you from nothing to a built app in five steps. Before you choose chroma dev vs --no-desktop, read Runtime modes for how Portable (web) and Executable (Desktop) differ. For a guided tour of the project files, continue with Your first app.

Prerequisites

The Chroma CLI is all you need. The installer ships the engine binary, which contains the dev server, the preview server, the compiler (bundling and minifying .chr), and the optional build plugins. There is no Node.js, no npm, and no node_modules, and a Chroma project has no package.json.

CommandNeeds
InstallerA shell with unzip (macOS/Linux), or PowerShell (Windows).
chroma new, chroma dev, chroma preview, chroma build, chroma validate, chroma addNothing else. Works offline.
Zip of the build (package.zip)zip on PATH (otherwise a .tar.gz is written).

The dynamic and standard templates set engine.rebuildWasm: false, so chroma build uses the engine already compiled in pkg/. Only if you set "rebuildWasm": true (to recompile the engine from Rust source, from a source-checkout install) do you need Rust, the wasm32-unknown-unknown target, and wasm-pack. Every command and error is listed in the CLI reference.

1. Install the CLI

Chroma is free to download and use, including in production and in commercial products, and is licensed under the GNU GPL v3; see Licensing.

sh <(curl https://docs.targapps.xyz/sh)

sh <(curl ...) uses process substitution, which works in bash and zsh. In other shells, use curl -fsSL https://docs.targapps.xyz/sh | sh. The script needs curl and unzip.

The one-line commands download the package from https://docs.targapps.xyz/chroma-cli.zip to a temporary folder, run the installer, and delete the temporary files.

chroma install installs the chroma command, the engine binary (dev server, preview server, build, and compiler), chroma-desktop, the templates, the first-party plugins, and the prebuilt engine under ~/.chroma, and adds ~/.chroma/bin to your PATH. Open a new shell and confirm:

chroma --version

If PowerShell blocks the script, run powershell -ExecutionPolicy Bypass -File .\chroma.ps1 install. Install layout and troubleshooting: CLI reference.

2. Create an app

chroma new my-app --template dynamic
cd my-app
TemplateUse it for
dynamicES modules under src/**/*.chr, bundled by chroma build. Recommended.
standarddynamic plus a Chroma-Fs storage example.
staticFlat HTML and JS, no bundler.

Template contents: Templates.

3. Run it

chroma dev

The dynamic template sets dev.desktop: true, so chroma dev opens the app in Chroma Desktop. To use a browser tab instead, run chroma dev --no-desktop; the page then reloads automatically when you save (Live reload). The port comes from chroma.json (dev.port, 5173 in the dynamic template) or --port.

4. Edit it

Open src/components/Counter.chr and change the label:

// src/components/Counter.chr
import { hookState, e } from "../../pkg/chroma.js";

export function Counter() {
  const [count, setCount] = hookState(0);
  return e(
    "button",
    { onClick: () => setCount(count() + 1) },
    "Clicks: ",
    count,
  );
}

Save the file. In a browser tab (--no-desktop) the page reloads by itself; Desktop develop mode does not reload, so re-run chroma dev to see changes. Before moving on, read the one rule: reactive children and attributes are passed as functions.

5. Build it

chroma validate
chroma build
chroma preview

chroma build bundles and minifies your .chr files with Chroma's own compiler and writes the result to dist/ (and a .zip next to it when package.zip is true). chroma preview serves dist/ exactly like a static host, so you can check the production output before you upload it. Host dist/ on any static server (Portable), or import the zip into Chroma Desktop (Executable). The build artifact is the same; plugins and storage behave differently per host — see Runtime modes. Flags and manifest fields: CLI, chroma.json.

Build the engine from source

Skip this unless you are working on the engine itself. It requires Rust with the wasm32-unknown-unknown target and wasm-pack. From the Chroma/ directory of the repository:

./build.sh

This runs wasm-pack build --target web, adds an auto-init line to pkg/chroma.js, and syncs pkg/ to the CLI package.

Where to go next

On this page