Origin Private File System

The Fastest Storage You Have Never Used

The Origin Private File System (OPFS) is the storage API most developers have never heard of, and it changes everything about what is possible in the browser. While IndexedDB gives you a structured database and the Cache API gives you HTTP response storage, OPFS gives you something fundamentally different: raw, byte-level file access — like writing to a file system, but sandboxed per origin and invisible to the user.

The killer feature is createSyncAccessHandle(). In a Web Worker, you get synchronous read/write/flush operations on files with zero async overhead. No promises, no callbacks, no transactions. Just raw byte I/O at speeds 3-4x faster than IndexedDB. This is why Adobe chose OPFS for Photoshop on the Web. It is why SQLite WASM uses OPFS as its persistence layer. It is how you build database-grade performance in the browser.

Getting Started: The Directory Handle

Everything starts with navigator.storage.getDirectory(), which returns a handle to the root directory of your origin's private file system.

const root = await navigator.storage.getDirectory();

const configDir = await root.getDirectoryHandle("config", { create: true });
const dataDir = await root.getDirectoryHandle("data", { create: true });

const configFile = await configDir.getFileHandle("settings.json", { create: true });
const dataFile = await dataDir.getFileHandle("records.bin", { create: true });

Directory Operations

// List directory contents
for await (const [name, handle] of root) {
  console.log(name, handle.kind); // "config" "directory" or "data.bin" "file"
}

// Remove a file
await root.removeEntry("old-file.txt");

// Remove a directory and all its contents
await root.removeEntry("temp", { recursive: true });

// Resolve a path from root to a nested handle
const path = await root.resolve(nestedFileHandle);
// Returns ["data", "sub", "file.bin"] or null if not a descendant

The Async API: Main Thread Access

The async API works on the main thread (and in Workers). It uses writable streams for writing and File objects for reading.

Writing Files (Async)

const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle("data.json", { create: true });

const writable = await fileHandle.createWritable();
await writable.write(JSON.stringify({ users: [1, 2, 3] }));
await writable.close(); // data is only committed on close

// You can also write at specific positions
const writable2 = await fileHandle.createWritable({ keepExistingData: true });
await writable2.seek(10); // move to byte offset 10
await writable2.write("inserted text");
await writable2.close();

Reading Files (Async)

const fileHandle = await root.getFileHandle("data.json");
const file = await fileHandle.getFile(); // returns a File object (like from an input)
const text = await file.text();
const data = JSON.parse(text);

// For binary data
const buffer = await file.arrayBuffer();
const bytes = new Uint8Array(buffer);

The Sync API: Worker-Only, Maximum Performance

This is where OPFS shines. createSyncAccessHandle() gives you synchronous read/write/flush access to a file — but only inside a Web Worker (or a dedicated Worker, SharedWorker, or service worker). Synchronous means zero async overhead: no microtask queue scheduling, no promise resolution delays, just direct memory-mapped I/O.

// worker.js
const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle("database.bin", { create: true });
const accessHandle = await fileHandle.createSyncAccessHandle();

// Write bytes synchronously
const encoder = new TextEncoder();
const data = encoder.encode("Hello, OPFS!");
const bytesWritten = accessHandle.write(data, { at: 0 });

// Read bytes synchronously
const readBuffer = new Uint8Array(bytesWritten);
const bytesRead = accessHandle.read(readBuffer, { at: 0 });
const decoder = new TextDecoder();
console.log(decoder.decode(readBuffer)); // "Hello, OPFS!"

// Get file size
const size = accessHandle.getSize();

// Truncate file
accessHandle.truncate(0); // clear file
accessHandle.truncate(1024); // resize to 1024 bytes

// Flush to disk (ensures durability)
accessHandle.flush();

// Always close when done
accessHandle.close();

Why Sync Access is Faster

Every IndexedDB operation goes through the async pipeline: your request enters a queue, the browser processes it on a separate thread, the result comes back through a promise resolution on the microtask queue. Even a simple get() has microseconds of scheduling overhead.

OPFS sync access skips all of that. The Worker thread directly reads and writes memory-mapped file regions. For workloads that make thousands of small reads/writes (like a database engine), this difference compounds dramatically.

IndexedDB single read:    ~0.5ms (async overhead + IPC + deserialization)
OPFS sync single read:    ~0.05ms (direct memory access)
Speedup:                  ~10x per operation

IndexedDB 10,000 reads:   ~5,000ms
OPFS sync 10,000 reads:   ~500ms

OPFS + SQLite WASM: A Full Database in the Browser

The most impactful use of OPFS is as the storage backend for SQLite compiled to WebAssembly. The official SQLite project provides a WASM build with an OPFS-backed VFS (Virtual File System) that uses createSyncAccessHandle() for all I/O.

The opfs-sahpool VFS

The opfs-sahpool VFS (introduced in SQLite 3.43) pre-allocates a pool of OPFS files and maps SQLite database pages to them. This avoids the overhead of creating and opening file handles for every database operation.

// worker.js — SQLite WASM with OPFS
import sqlite3InitModule from "@sqlite.org/sqlite-wasm";

const sqlite3 = await sqlite3InitModule();

const db = new sqlite3.oo1.OpfsDb("/myapp.db");

db.exec("CREATE TABLE IF NOT EXISTS products (id INTEGER PRIMARY KEY, name TEXT, price REAL)");
db.exec("INSERT INTO products VALUES (1, 'Widget', 9.99)");

const results = [];
db.exec({
  sql: "SELECT * FROM products WHERE price < 20",
  callback: (row) => results.push(row),
});

db.close();

Performance: SQLite WASM + OPFS vs Raw IndexedDB

SQLite brings SQL queries, joins, aggregations, full-text search (FTS5), JSON functions, and ACID transactions — all backed by OPFS's high-performance I/O. For apps that need serious data management (note-taking, project management, CRM, analytics), this combination is the state of the art.

Practical Patterns

Pattern 1: Large File Processing in a Worker

// main.js
const worker = new Worker("processor.js");

worker.postMessage({ action: "process", filename: "dataset.csv" });

worker.onmessage = (event) => {
  if (event.data.type === "progress") {
    updateProgressBar(event.data.percent);
  } else if (event.data.type === "complete") {
    displayResults(event.data.results);
  }
};

// processor.js (Worker)
self.onmessage = async (event) => {
  const { action, filename } = event.data;

  const root = await navigator.storage.getDirectory();
  const handle = await root.getFileHandle(filename);
  const access = await handle.createSyncAccessHandle();

  const size = access.getSize();
  const chunkSize = 64 * 1024; // 64KB chunks
  let offset = 0;
  let results = [];

  while (offset < size) {
    const buffer = new Uint8Array(Math.min(chunkSize, size - offset));
    access.read(buffer, { at: offset });

    results.push(processChunk(buffer));
    offset += chunkSize;

    self.postMessage({
      type: "progress",
      percent: Math.round((offset / size) * 100),
    });
  }

  access.close();
  self.postMessage({ type: "complete", results });
};

Pattern 2: Write-Ahead Log for Crash Recovery

// Worker: append-only write-ahead log
class WriteAheadLog {
  constructor(accessHandle) {
    this.handle = accessHandle;
    this.offset = accessHandle.getSize();
  }

  append(entry) {
    const data = new TextEncoder().encode(JSON.stringify(entry) + "\n");
    this.handle.write(data, { at: this.offset });
    this.offset += data.byteLength;
    this.handle.flush(); // ensure durability
  }

  readAll() {
    const size = this.handle.getSize();
    if (size === 0) return [];
    const buffer = new Uint8Array(size);
    this.handle.read(buffer, { at: 0 });
    const text = new TextDecoder().decode(buffer);
    return text.trim().split("\n").map(line => JSON.parse(line));
  }

  truncate() {
    this.handle.truncate(0);
    this.offset = 0;
  }
}

Pattern 3: Storing and Retrieving Binary Assets

async function saveImage(name, blob) {
  const root = await navigator.storage.getDirectory();
  const imagesDir = await root.getDirectoryHandle("images", { create: true });
  const fileHandle = await imagesDir.getFileHandle(name, { create: true });
  const writable = await fileHandle.createWritable();
  await writable.write(blob);
  await writable.close();
}

async function loadImage(name) {
  const root = await navigator.storage.getDirectory();
  const imagesDir = await root.getDirectoryHandle("images");
  const fileHandle = await imagesDir.getFileHandle(name);
  const file = await fileHandle.getFile();
  return URL.createObjectURL(file);
}

Browser Support and Gotchas

Challenge: Build an OPFS-Backed Key-Value Store

// Build a simple key-value store backed by OPFS that runs in a Worker.
// Requirements:
// 1. get(key) - returns the value or undefined
// 2. set(key, value) - stores a JSON-serializable value
// 3. delete(key) - removes a key
// 4. All data persists across page reloads
// 5. Use a single file with JSON for simplicity
// 6. Handle the case where the file does not exist yet
//
// Bonus: Can you identify the performance limitation of this approach
// compared to IndexedDB? When would you choose this over IndexedDB?

Key Rules