Origin Private File System (OPFS)
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.
Binary Persistence: IndexedDB Blobs vs OPFS SyncAccessHandle
const tx = db.transaction('chunks', 'readwrite');
tx.objectStore('chunks').put(uint8Chunk, offset);
// Serializes via structuredClone per writeIncurs structuredClone + B-tree transaction commit per chunk.
const handle = await fileHandle.createSyncAccessHandle();
handle.write(uint8Chunk, { at: offset });
handle.flush();
handle.close();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.
- Private Root:
navigator.storage.getDirectory()returns aFileSystemDirectoryHandleinvisible to the user's OS file picker. - Exclusive Sync Handle: Calling
fileHandle.createSyncAccessHandle()in a worker acquires an exclusive lock and exposesread(buf, { at })andwrite(buf, { at }). - Zero Serialization: Bytes move straight from a Wasm linear memory
Uint8Arrayto the OS file buffer withoutstructuredCloneor transaction wrappers.
// 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
FileSystemFileHandlefor 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
- Multi-tab lock contention:
createSyncAccessHandle()throwsNoModificationAllowedErrorif another tab holds the file lock; wrap access innavigator.locks.request(). - Forgetting
flush()andclose(): Buffered writes may vanish on sudden tab termination, and unclosed handles block future workers from opening the file.
- 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
Stateful worker actors persist snapshots synchronously using OPFS createSyncAccessHandle.
FileSystemSyncAccessHandle is only exposed inside DedicatedWorkerGlobalScope.
OPFS shares the origin's storage quota pool and eviction rules with IndexedDB.
Web Locks prevent NoModificationAllowedError when multiple tabs open the same OPFS file.
Streaming fetch bodies directly into FileSystemWritableFileStream avoids buffering gigabytes in RAM.
OPFS provides raw byte-level file handles without structured-clone or transaction overhead.