# opfs-worker
> Node.js-style filesystem API for OPFS — auto-creates a Worker for you, with optional async and SharedWorker modes
Latest version **2.2.1** (published 2026-07-26) · MIT license · 0 weekly downloads
## Install
```sh
npm install opfs-worker
pnpm add opfs-worker
yarn add opfs-worker
bun add opfs-worker
```
## Health
**Score 75/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 2.2.1 |
| Published | 2026-07-26 |
| First published | 2025-08-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 2 |
| Unpacked size | 2.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | Maksim Kachurun |
| Maintainers | kachurun |
| Keywords | opfs, origin-private-file-system, web-worker, filesystem, browser-storage, file-api, typescript |
## Links
- npm: https://www.npmjs.com/package/opfs-worker
- Repository: https://github.com/kachurun/opfs-worker
- Homepage: https://github.com/kachurun/opfs-worker#readme
- Issues: https://github.com/kachurun/opfs-worker/issues
- npm.io page: https://npm.io/package/opfs-worker
## Dependencies (2)
- [comlink](https://npm.io/package/comlink.md) ^4.4.2
- [minimatch](https://npm.io/package/minimatch.md) ^10.0.3
## Alternatives
- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads
## Recent versions
- 2.2.1 (latest) — 2026-07-26
- 2.2.0 — 2026-07-26
- 2.1.2 — 2026-07-26
- 2.1.1 — 2026-07-26
- 2.1.0 — 2026-07-25
- 2.0.0 — 2026-07-24
- 1.3.2 — 2026-02-27
- 1.3.1 — 2025-09-07
- 1.3.0 — 2025-09-07
- 1.2.4 — 2025-09-04
- 1.2.3 — 2025-08-25
- 1.2.2 — 2025-08-20
- 1.2.1 — 2025-08-20
- 1.2.0 — 2025-08-20
- 1.1.0 — 2025-08-19
- … 18 more at https://npm.io/package/opfs-worker/versions
## README
# OPFS Worker
A full-featured filesystem layer for the browser, built on the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/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 →](https://kachurun.github.io/opfs-worker/)**
## Features
→ **File API** — `readFile`, `writeFile`, `mkdir`, `stat`, `rename`, `copy`, `readDir`; encodings, extension-based detection, `string | URL` paths. [Docs](docs/api/README.md#facade)
→ **File descriptors** — `open` / `read` / `write` at an offset, plus `ftruncate` and `fsync`. [Docs](docs/api/file-descriptors.md)
→ **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](docs/guides/dedicated.md)
→ **Async** — same API on the main thread, no worker. No FDs. Writes need Safari 26+ (Safari 18 and older can only read). [Docs](docs/guides/async.md)
→ **SharedWorker** — one instance shared across tabs. Same limits as async (no FDs, Safari 26+ for writes). [Docs](docs/guides/sharedworker.md)
→ **Bring your own worker** — use it directly in a worker you already run, or load a prebuilt worker script. [Docs](docs/guides/pure.md)
→ **Large files** — stream reads (`readBlob`) and writes (`importStream` / `importFiles`) without buffering everything. [Docs](docs/guides/streaming.md) · [Upload](docs/guides/uploading.md) · [Download](docs/guides/downloading.md)
→ **Watch** — change events with a Node-style `watch(path, listener)` (BroadcastChannel under the hood, including across tabs). [Docs](docs/guides/watching.md)
→ **Hashing** — `stat()` can include an etag or a SHA hash (SHA skipped above a size cap). [Docs](docs/guides/hashing.md)
## Installation
```bash
npm install opfs-worker
```
## Quick start
```typescript
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](docs/api/README.md) — entries, facade methods, options, trade-offs
- [File descriptors](docs/api/file-descriptors.md) — positional `open` / `read` / `write`
- [Types](docs/types.md)
- [Migration from 1.x](docs/migration.md)
## Guides
| Guide | About |
| ------------------------------------------------- | --------------------------------------------------------- |
| [Dedicated worker](docs/guides/dedicated.md) | How to use OPFS via a dedicated worker (the default path) |
| [Async](docs/guides/async.md) | How to use OPFS on the main thread, without a worker |
| [SharedWorker](docs/guides/sharedworker.md) | How to share one filesystem across all tabs |
| [Pure classes](docs/guides/pure.md) | How to drop OPFS into a worker you already run |
| [Streaming](docs/guides/streaming.md) | How to read/write large files without buffering |
| [Uploading from disk](docs/guides/uploading.md) | Pickers, paste, drag-and-drop into `importFiles` |
| [Downloading to disk](docs/guides/downloading.md) | `readBlob` → `` / `showSaveFilePicker` |
| [Watching](docs/guides/watching.md) | How to listen for file changes across tabs |
| [Hashing](docs/guides/hashing.md) | How file hashes / etags work on `stat` and watch events |
## Development
```bash
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](https://github.com/kachurun)
---
_Source: https://npm.io/package/opfs-worker · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._