Plugin system

Chroma apps extend the engine with plugins — optional packages vendored into plugins/<name>/ and listed in chroma.json.

Declaring plugins

{
  "name": "my-app",
  "mode": "dynamic",
  "plugins": ["chroma-fs"],
  ...
}

Install and scaffold

1. chroma install — builds Chroma-Fs from the workspace checkout (when Chroma-Fs/ is present) into $CHROMA_HOME/plugins/chroma-fs. Also builds chroma-desktop for develop mode when Chroma-Desktop/ is available.
2. chroma new — copies each plugin from $CHROMA_HOME/plugins/<name> into the new project's plugins/ directory. The standard template includes Chroma-Fs by default; static/dynamic add it when plugins: ["chroma-fs"] is set.

Runtime loader

Templates include plugins/loader.js:

export async function loadPlugins() {
  const manifest = await fetch("./chroma.json", { cache: "no-store" }).then((r) => r.json());
  const loaded = {};

  for (const name of manifest.plugins ?? []) {
    if (name === "chroma-fs") {
      const { createStorage } = await import("./chroma-fs/index.js");
      loaded.fs = await createStorage({ configPath: "./chroma-fs.json" });
    }
  }

  return loaded;
}

Call loadPlugins() before render() so storage is ready when components mount.

Build output

chroma build copies plugins/ and chroma-fs.json into dist/ for both static and dynamic modes, so packaged apps keep the plugin and its config at runtime.

Adding more plugins

To add a future plugin:

1. Ship it under $CHROMA_HOME/plugins/<name> via chroma install
2. Add "<name>" to plugins in chroma.json
3. Extend plugins/loader.js with the import/init logic for that plugin