idb-vfs

What It Is

When building browser-based code editors or interactive development environments (such as Concept Ninjas AI Lab), candidate code cannot constantly roundtrip across the network on every keystroke or local file navigation. The browser needs a robust, fast, local virtual filesystem that mimics real OS directory trees, supports binary and text files, and survives page reloads.

localStorage is completely inadequate for this: it has a 5MB storage ceiling, blocks the main JavaScript thread with synchronous I/O, and lacks hierarchical tree structures.

I engineered and published idb-vfs to provide a production-ready, asynchronous virtual filesystem layer built on top of browser IndexedDB and Dexie.js, complete with directory trees, metadata, and automated revision history.

---

What It Does

• Full Hierarchical Tree Structure: Create, move, rename, read, and delete nested directories and files using standard Unix-style paths (/src/index.ts).
• In-Browser Persistence with IndexedDB: Fast, asynchronous storage with substantial storage quotas that never freezes the main thread.
• Built-in Versioning & Revisions: Tracks changes to files so web IDEs can provide undo/redo, revision diffing, and recovery if candidate code gets corrupted.
• Unified Workspace Abstraction: Allows Monaco / VS Code editor components, terminal emulators, AI coding agents, and execution sandbox synchronizers to all read and write from a single consistent storage interface.

---

Installation & Quick Usage

npm i idb-vfs

import { VirtualFileSystem } from "idb-vfs";

const vfs = new VirtualFileSystem({ dbName: "workspace-project" });
await vfs.init();

// Write file with directories automatically created
await vfs.writeFile("/src/index.ts", "console.log('Hello from VFS');");

// Read file content
const content = await vfs.readFile("/src/index.ts");

// List directory contents
const files = await vfs.readDir("/src");

---

Why I Built It & Open Sourced It

While developing the AI Lab platform at Concept Ninjas, we needed a shared layer that both the Monaco code editor and the AI coding agent could concurrently access in the candidate's browser. Rather than coupling this storage logic deeply into the proprietary UI components, I architected it as a modular, standalone library.

After verifying its performance across thousands of live candidate assessment sessions, I packaged and released it to the broader open-source community for developers building browser IDEs, markdown notebooks, and offline-first web apps.

---

Key Learnings & Takeaways

• Decouple storage engines from UI components: Packaging the virtual filesystem as an independent module allowed us to write unit tests for file operations without mounting complex React editor components.
• IndexedDB requires clean abstraction: Raw IndexedDB APIs are notoriously verbose and cumbersome. Wrapping it in an intuitive path-based abstraction dramatically accelerates development velocity.