@openislands/storage

@openislands/storage

Swappable storage ports for OpenIslands, so server-side I/O never touches the filesystem directly.

OpenIslands reads and writes through three ports instead of calling node:fs: a ContentStore for app content, an AppStateStore for the tool's own .openislands/ state, and a VersionStore for editor file history. Each ships with a local-disk adapter, and configureStorage() swaps in a different backend at boot, without changing a single call site.

@openislands/storage is part of OpenIslands. The compiler, runtime, and MCP server all sit on top of it, so it usually arrives transitively through npx openislands. Install it directly when you're writing a custom backend: a database- or cloud-backed store in place of local disk.

Install

npm i @openislands/storage

Zero runtime dependencies. The bundled adapters use node:fs, so they're server-side only. ESM-only, Node ≥ 20.

Usage

import { getContentStore, configureStorage } from "@openislands/storage";

// Default: the local-disk adapter, keyed by project directory.
const content = getContentStore("/path/to/my-app");
await content.writeText("data/x.csv", "a,b\n1,2\n");
const text = await content.readText("data/x.csv");

// Swap in your own backend once at boot. Omitted ports keep their default.
configureStorage({
  content: (appKey) => new MyContentStore(appKey),
  versions: (appKey) => new MyVersionStore(appKey),
});

Every store is resolved by an opaque app key (today, the project directory). getContentStore and getAppStateStore fall back to local disk; getVersionStore has no default and throws until you configure one.

The three ports

LocalContentStore and LocalAppStateStore are the default disk adapters. VersionStore ships as an interface only; its disk implementation lives in the runtime, registered at boot.

Documentation

• OpenIslands docs
• GitHub

License

MIT Luka Isailovic