Your first app

This tutorial builds on the Quick start. You will look at what chroma new generated, set up editor checks, and optionally add storage.

Checklist

• Install the CLI (Quick start)
• Create a project: chroma new my-app --template dynamic (or standard for storage)
• Open the project folder, not a single file, in VS Code or a compatible editor
• Install the Chroma extension (publisher targapps, Open VSX)
• Save chroma.json and check the Problems panel
• Read the .chr format before adding files under src/

Step 1: Run the generated app

chroma new hello-chroma --template dynamic
cd hello-chroma
chroma dev

The CLI prints the URL it serves. The port comes from chroma.json (dev.port) or --port.

Step 2: Know the project files

Folder rules and build.jsEntry: .chr format.

Add a component:

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

export function Greeting() {
  const [name, setName] = hookState("world");
  return e(
    "main",
    null,
    e("p", null, "Hello, ", name),
    e("input", {
      value: name,
      onInput: (ev) => setName(ev.target.value),
    }),
  );
}

Use it from App:

// src/App.chr
import { e } from "../pkg/chroma.js";
import { Greeting } from "./components/Greeting.chr";

export function App() {
  return e("div", null, e(Greeting));
}

Step 3: Editor checks and linting

The VS Code extension and @chroma/linter share one rule set: JSON Schema validation for manifests, plugin and build-entry checks, and .chr conventions.

1. Install the Chroma extension.
2. Open the folder that contains chroma.json.
3. Save chroma.json; the project is linted on save.
4. Run Chroma: Lint Project (chroma.lintProject) from the Command Palette.

Details: VS Code extension, Linter.

Step 4: Storage with Chroma-Fs (optional)

chroma new notes --template standard
cd notes
chroma dev

The standard template adds a storage example and chroma-fs.json. Backends and API: Chroma-Fs.

// src/storage.chr
import { createChromaFs } from "@chroma/fs";

const fs = await createChromaFs({ configPath: "./chroma-fs.json" });
await fs.writeFile("notes/hello.txt", "Hello from Chroma-Fs");

When something goes wrong

Where to go next