Chroma-Fs
API
Reference for createChromaFs, createStorage, and the file methods available on every Chroma-Fs backend.
createChromaFs(options?)
Resolves the config, detects the platform, and returns a ChromaFs instance. Use this in app code.
// src/storage.chr
import { createChromaFs } from "@chroma/fs";
const fs = await createChromaFs({ configPath: "./chroma-fs.json" });Options (CreateStorageOptions)
| Field | Type | Required | Description |
|---|---|---|---|
config | Partial<ChromaFsConfig> | No | Inline config. Merged over the file when configPath is also set. |
configPath | string | No | URL or path of chroma-fs.json. Without config or configPath, it tries chroma-fs.json and falls back to defaults. |
adapter | TauriFsAdapter | No | Custom filesystem adapter, for tests or a custom bridge. Forces the filesystem backend. |
Errors
Filesystem backend requires Chroma Desktop (postMessage bridge) or a Tauri host with @tauri-apps/plugin-fs.is thrown whenbackendisfilesystemoutside Desktop and Tauri.
createStorage(options?)
Same options and backends, but returns the plain Storage object instead of a ChromaFs instance. Both expose the same methods. The plugin loader calls createStorage through the bootstrapFs hook and exposes the result as plugins.fs; in your own code prefer createChromaFs.
Methods
All methods are async. Paths use / and are relative to the storage root.
| Method | Description |
|---|---|
readFile(path) | Returns Uint8Array |
readText(path) | Returns a UTF-8 string |
writeFile(path, data) | data is a string or Uint8Array; parent directories are created |
delete(path) | Removes a file, or a directory with its contents |
exists(path) | Returns boolean |
list(path?) | Direct children as FileEntry[] |
mkdir(path) | Creates a directory |
rmdir(path, { recursive? }) | Removes an empty directory, or a full one when recursive is true |
stat(path) | Returns FileEntry or null |
FileEntry
interface FileEntry {
name: string;
path: string;
kind: "file" | "directory";
size?: number;
modifiedAt?: number;
}Utilities
@chroma/fs also exports:
- Config:
loadConfig,parseConfig,mergeConfig,defaultConfig,detectPlatform,resolveBackend - Paths:
normalizePath,joinPath,parentPath,baseName - Bridge:
createPostMessageAdapter,isInIframe,hasTauriRuntime,createDefaultTauriFsAdapter
Example: settings helper
// src/settings.chr
import { createChromaFs } from "@chroma/fs";
let fsPromise = null;
export function getFs() {
if (!fsPromise) {
fsPromise = createChromaFs({ configPath: "./chroma-fs.json" });
}
return fsPromise;
}
export async function saveSettings(settings) {
const fs = await getFs();
await fs.writeFile("settings.json", JSON.stringify(settings, null, 2));
}