Backends

Chroma-Fs implements two storage backends behind one API. The factory (createChromaFs) selects the backend from config and runtime environment.

IndexedDB

Used for static apps and any browser context without Tauri.

• Virtual directory tree stored in a single IndexedDB object store
• Paths normalized to forward slashes (notes/hello.txt)
• Parent directories created implicitly on writeFile
• delete on a directory removes all descendants

No native files are created — data stays in the browser profile until cleared.

Filesystem (Tauri / Desktop)

Used when backend: "filesystem" and a filesystem adapter is available.

Direct Tauri (rare)

If the app runs with window.__TAURI__ and is not in an iframe, Chroma-Fs uses @tauri-apps/plugin-fs via createDefaultTauriFsAdapter, scoped to AppLocalData + basePath.

Chroma Desktop iframe bridge (default for packaged apps)

Chroma Desktop hosts apps in an <iframe> at http://127.0.0.1:<port>/<app-id>/index.html. Iframes cannot call Tauri directly.

Flow:

1. App imports @chroma/fs → detects iframe + desktop → createPostMessageAdapter()
2. Adapter sends { channel: "chroma-fs", id, op, args } to window.parent
3. Chroma Desktop parent handles the message and calls scoped Rust commands
4. Parent responds with { channel: "chroma-fs", id, ok, result | error }

Scoped data directories

Rust commands in Chroma Desktop resolve paths under:

<tauri-app-data>/apps/<app-id>/data/<relative-path>

• Imported apps: app-id is the import folder name
• Develop mode (chroma dev on dynamic): app-id is develop

Path traversal (..) is rejected.

Tauri commands (Chroma Desktop)

tauri-plugin-fs is registered with scoped capabilities (fs:scope-appdata-recursive) for the shell; app iframe traffic goes through the postMessage bridge and Rust commands for tighter per-app isolation.

Backend selection diagram

Testing adapters

Use createMockTauriFsAdapter patterns or pass a custom adapter in createChromaFs({ adapter }) for unit tests without IndexedDB or Tauri.