Quick Start

From install to your first snapshot in about a minute.

#Install

npm i unfs

#Your first filesystem

Create a store, open a filesystem over it, then use it like node:fs:

import { createFs, initStore, memoryStore } from "unfs";

const store = await initStore(memoryStore()); // any KVStore works
const fs = createFs(store); // tracks the "head" ref by default

await fs.mkdir("/docs");
await fs.writeFile("/docs/hello.txt", "hello unfs\n");
await fs.symlink("hello.txt", "/docs/link");

await fs.readFile("/docs/link", "utf8"); // "hello unfs\n" (symlinks are followed)
await fs.readdir("/docs", { withFileTypes: true }); // Dirent[]
(await fs.stat("/docs/hello.txt")).size; // 11
await fs.cp("/docs", "/backup", { recursive: true }); // instant, whatever the size
await fs.rename("/docs/hello.txt", "/docs/hi.txt");

Two lines of setup and the rest is node:fs. initStore prepares a backend and createFs opens a filesystem over it.

memoryStore() is the simplest backend there is. Swap it for fsStore(".data/store") to keep your data on disk, or for a networked store to put it somewhere else. Nothing below that line changes.

#What just happened

Each of those writes built a new snapshot and moved "head" forward.

The cp didn't copy any bytes. /backup points at the same blocks as /docs, which is why it finishes instantly no matter how large the directory is. And nothing you wrote was modified in place, so every earlier version of the tree is still sitting in the store.

That's the whole model, and it's what makes cheap snapshots, copies, and exports possible. The introduction walks through why it works that way.

#Next steps

You already know enough to build something. When you need more:

• Pick a real store. Integrations covers the on-disk driver, any unstorage driver, and a remote HTTP store.
• The Filesystem API for the full surface, watching for changes, and the synchronous version.
• Performance for when writing many files or reading many paths starts to feel slow.