Targ Apps Docs
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)

FieldTypeRequiredDescription
configPartial<ChromaFsConfig>NoInline config. Merged over the file when configPath is also set.
configPathstringNoURL or path of chroma-fs.json. Without config or configPath, it tries chroma-fs.json and falls back to defaults.
adapterTauriFsAdapterNoCustom 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 when backend is filesystem outside 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.

MethodDescription
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));
}

On this page