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