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
filesysteminchroma-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 devTo add storage to an existing app:
chroma fs init # creates chroma-fs.json with defaults for the app modeThen 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
| Context | Backend | Location |
|---|---|---|
| Static template, browser | IndexedDB | Browser profile (chroma-fs database) |
| Dynamic app in Chroma Desktop | Filesystem | <app-data>/apps/<app-id>/data/ |
chroma dev with desktop | Filesystem | <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.jsonschema - API for every method
- Templates for the
standardtemplate with the file explorer - CLI for
chroma fs init
Chroma-Fs is licensed under the GNU GPL v3. © Targ Apps. See Licensing.