opfs-worker

OPFS Worker

A full-featured filesystem layer for the browser, built on the Origin Private File System.

opfs-worker gives your app a familiar Node.js-style API for working with files and directories while handling the awkward browser parts for you: Worker setup, concurrent access, encodings, large-file streaming, change events, and cross-tab coordination.

Choose the runtime that fits your app: use a dedicated Worker for the fastest and widest-compatible path, run the async backend directly on the current thread, or share one filesystem process across every tab with SharedWorker.

No permission prompt or file picker is required. Files stay private to the current origin and live within the browser’s site storage, so clearing site data removes them.

Try the demo →

Features

→ File API — readFile, writeFile, mkdir, stat, rename, copy, readDir; encodings, extension-based detection, string | URL paths. Docs

→ File descriptors — open / read / write at an offset, plus ftruncate and fsync. Docs

→ Concurrent access — operations on the same path are serialized, so parallel reads and writes do not fail because another sync access handle is open.

→ Dedicated worker (default) — createOPFS() sets up the worker for you. Fastest path, supports FDs, writes work in older Safari too. Docs

→ Async — same API on the main thread, no worker. No FDs. Writes need Safari 26+ (Safari 18 and older can only read). Docs

→ SharedWorker — one instance shared across tabs. Same limits as async (no FDs, Safari 26+ for writes). Docs

→ Bring your own worker — use it directly in a worker you already run, or load a prebuilt worker script. Docs

→ Large files — stream reads (readBlob) and writes (importStream / importFiles) without buffering everything. Docs · Upload · Download

→ Watch — change events with a Node-style watch(path, listener) (BroadcastChannel under the hood, including across tabs). Docs

→ Hashing — stat() can include an etag or a SHA hash (SHA skipped above a size cap). Docs

Installation

npm install opfs-worker

Quick start

import { createOPFS } from 'opfs-worker';

// Starts a dedicated worker and returns a Node-like fs API
const fs = createOPFS({
  root: '/my-app',
  hashAlgorithm: 'SHA-256'
});

await fs.mkdir('/project');
await fs.writeFile('/project/hello.txt', 'Hello, OPFS!');
await fs.rename('/project/hello.txt', '/project/readme.txt');

const files = await fs.readDir('/project');
const text = await fs.readFile('/project/readme.txt'); // 'Hello, OPFS!'

// Tear down watches, close the backend, and terminate the worker
fs.dispose();

Choose a mode

What you want	Use
Node-like fs via dedicated worker (default, works everywhere)	createOPFS()
Node-like fs on the main thread (modern browsers / Safari 26+)	createOPFSAsync() from opfs-worker/async
Node-like fs via SharedWorker (modern browsers / Safari 26+)	createOPFSShared() from opfs-worker/sharedworker
OPFS inside a worker you already run (classes only)	OPFSSync / OPFSAsync from opfs-worker/pure

Docs

• API overview — entries, facade methods, options, trade-offs
• File descriptors — positional open / read / write
• Types
• Migration from 1.x

Guides

Guide	About
Dedicated worker	How to use OPFS via a dedicated worker (the default path)
Async	How to use OPFS on the main thread, without a worker
SharedWorker	How to share one filesystem across all tabs
Pure classes	How to drop OPFS into a worker you already run
Streaming	How to read/write large files without buffering
Uploading from disk	Pickers, paste, drag-and-drop into importFiles
Downloading to disk	readBlob → <a download> / showSaveFilePicker
Watching	How to listen for file changes across tabs
Hashing	How file hashes / etags work on stat and watch events

Development

npm install
npm run build
npm run test
npm run lint
npm run type-check

Demo: npm run dev:demo / npm run build:demo / npm run preview.

Maintainer

Maintained with by @kachurun