Targ Apps Docs
Chroma-Fs

Chroma-Fs

Read and write files from a Chroma app with one API that uses IndexedDB in the browser and a real filesystem in Chroma Desktop.

Chroma-Fs (@chroma/fs) gives a Chroma app one storage API and picks the backend for you:

  • Static apps in a browser use IndexedDB.
  • Dynamic apps inside Chroma Desktop use real files under a per-app data directory.
  • Dynamic apps in a plain browser use IndexedDB, unless you force filesystem in chroma-fs.json (that requires a Tauri host and otherwise throws).

Chroma-Fs ships as a Chroma plugin (chroma-fs) and as the @chroma/fs package. Backend choice follows Chroma runtime mode (Portable web vs Executable Desktop). See the glossary for how the names relate.

In plain words: think of Chroma-Fs as a small disk inside your app. You save and read files by path, such as notes/todo.txt, without learning IndexedDB or desktop APIs.

Quick start

Create a project from the standard template, which includes Chroma-Fs and a file explorer demo:

chroma new my-app --template standard
cd my-app && chroma dev

To add storage to an existing app:

chroma fs init    # creates chroma-fs.json with defaults for the app mode

Then add "chroma-fs" to the plugins array in chroma.json.

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

const fs = await createChromaFs({ configPath: "./chroma-fs.json" });

await fs.mkdir("notes");
await fs.writeFile("notes/todo.txt", "Buy milk");
const entries = await fs.list("notes");
const text = await fs.readText("notes/todo.txt");

Paths always use /, including on Windows.

Where data lives

ContextBackendLocation
Static template, browserIndexedDBBrowser profile (chroma-fs database)
Dynamic app in Chroma DesktopFilesystem<app-data>/apps/<app-id>/data/
chroma dev with desktopFilesystem<app-data>/apps/develop/data/

To use the real filesystem during development, run chroma dev with dev.desktop: true in chroma.json (the default for the dynamic and standard templates). Apps in Desktop run inside an iframe, so filesystem calls travel over a postMessage bridge; see Backends.

Next

  • Configuration for the chroma-fs.json schema
  • API for every method
  • Templates for the standard template with the file explorer
  • CLI for chroma fs init

Chroma-Fs is licensed under the GNU GPL v3. © Targ Apps. See Licensing.

On this page