Web APIsBaseline · Widely

Origin Private File System (OPFS)

Mental Model

The Origin Private File System (OPFS) gives each origin a hidden, sandboxed directory on disk without user permission prompts. Inside a Dedicated Worker, createSyncAccessHandle() unlocks synchronous, in-place byte-range reads and writes at near-native speed.

Interactive Simulator

Binary Persistence: IndexedDB Blobs vs OPFS SyncAccessHandle

Lines of Code
Before
3
After
4
Reflows / Browser Cost
Before
Async IDB + Clone
After
Direct OS syscall
BeforeIndexedDB Async Transaction
const tx = db.transaction('chunks', 'readwrite');
tx.objectStore('chunks').put(uint8Chunk, offset);
// Serializes via structuredClone per write
Lines: 3Reflows: Async IDB + CloneDependencies: 0 kB

Incurs structuredClone + B-tree transaction commit per chunk.

After (Native)OPFS Worker SyncAccessHandle
const handle = await fileHandle.createSyncAccessHandle();
handle.write(uint8Chunk, { at: offset });
handle.flush();
handle.close();
Lines: 4Reflows: Direct OS syscallDependencies: 0 kB

Zero structuredClone; synchronous byte-range I/O in a worker.

Under the Hood

If IndexedDB is a notary public stamping every envelope, OPFS is a raw file descriptor handed directly to your Dedicated Web Worker.

  1. Private Root: navigator.storage.getDirectory() returns a FileSystemDirectoryHandle invisible to the user's OS file picker.
  2. Exclusive Sync Handle: Calling fileHandle.createSyncAccessHandle() in a worker acquires an exclusive lock and exposes read(buf, { at }) and write(buf, { at }).
  3. Zero Serialization: Bytes move straight from a Wasm linear memory Uint8Array to the OS file buffer without structuredClone or transaction wrappers.
JS
// Inside a Dedicated Worker
const root = await navigator.storage.getDirectory();
const file = await root.getFileHandle('db.sqlite', { create: true });
const access = await file.createSyncAccessHandle();

const page = new Uint8Array(4096);
access.read(page, { at: 0 });
access.write(page, { at: 4096 });
access.flush();
access.close();

Problem Genealogy

  • 2011 (FileSystem API, Chrome-only): Deprecated non-standard sandboxed filesystem never adopted by Firefox or Safari.
  • 2020 (File System Access API): Standardized FileSystemFileHandle for user-chosen files, plus the origin-private branch.
  • 2022+ (FileSystemSyncAccessHandle): Added synchronous worker I/O, unlocking production SQLite, DuckDB, and video editors in Wasm.

Production Pitfalls

Production Pitfall
  • Multi-tab lock contention: createSyncAccessHandle() throws NoModificationAllowedError if another tab holds the file lock; wrap access in navigator.locks.request().
  • Forgetting flush() and close(): Buffered writes may vanish on sudden tab termination, and unclosed handles block future workers from opening the file.
When Not to Use
  • When not to use OPFS: For small key-value settings or indexed JSON queries, IndexedDB avoids manual byte-offset management and exclusive file locking.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons