Backends
IndexedDB and filesystem backends, Tauri integration, and the Chroma Desktop postMessage bridge.
Chroma-Fs implements two storage backends behind one API. The factory (createChromaFs, or createStorage) selects the backend from config and runtime environment.
| Backend | Where data lives | When it is used |
|---|---|---|
| IndexedDB | Browser profile | Web-only apps, the static template, quick tests |
| Filesystem | <app-data>/apps/<id>/data/ in Chroma Desktop | Packaged apps, chroma dev with desktop |
In plain words: you do not call IndexedDB in your code. You configure chroma-fs.json and Chroma-Fs picks the backend. If data is not where you expect, check whether you are running in a browser or in Chroma Desktop (iframe plus postMessage bridge).
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 deleteon 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> served from a local http://127.0.0.1 address. Iframes cannot call Tauri directly.
Flow:
- App imports
@chroma/fs→ detects iframe + desktop →createPostMessageAdapter() - Adapter sends
{ channel: "chroma-fs", id, op, args }towindow.parent - Chroma Desktop parent handles the message and calls scoped Rust commands
- 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-idis the import folder name - Develop mode (
chroma devon dynamic):app-idisdevelop
Path traversal (..) is rejected.
Filesystem access is scoped to each app's own data directory; app iframe traffic goes through the bridge rather than direct Tauri access, which keeps apps isolated from each other.
Backend selection diagram
Testing adapters
In unit tests, pass an in-memory adapter to createChromaFs({ adapter }). It forces the filesystem backend without needing IndexedDB or Tauri.