OPFS VFS

A browser filesystem backed by the Origin Private File System. It provides POSIX-style file operations, write-ahead logging, crash recovery, and shared worker transport.

This is the standalone core distribution. It contains the library, its tests, and optional PGlite and just-bash adapters. It has no runtime dependencies for ordinary filesystem use.

The core is MIT-licensed. Publication is prepared under @opfs-vfs/opfs-vfs; see the release guide for initial availability.

Use

After the first public release:

npm install @opfs-vfs/opfs-vfs

Use the worker client from a browser page:

import { OpenFlags } from '@opfs-vfs/opfs-vfs';
import { OpfsVfsWorker } from '@opfs-vfs/opfs-vfs/worker';

const fs = new OpfsVfsWorker('documents.bin');
await fs.ready;
const fd = await fs.open('/hello.txt', OpenFlags.O_CREAT | OpenFlags.O_RDWR);
await fs.write(fd, new TextEncoder().encode('hello'));
await fs.fsync(fd);
await fs.close(fd);
await fs.closeVfs();

Serve over HTTPS or localhost. Synchronous worker calls use SharedArrayBuffer and require cross-origin isolation: Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp. Direct OpfsVfs mounts use synchronous OPFS handles and belong in a dedicated worker. See API and development.

Optional adapters

import { OpfsVfsPGliteAdapter } from '@opfs-vfs/opfs-vfs/pglite';
import { OpfsVfsJustBashAdapter } from '@opfs-vfs/opfs-vfs/just-bash';

Install @electric-sql/pglite when using the PGlite adapter. Pass a synchronous VFS instance to new OpfsVfsPGliteAdapter(vfs); shared clients must be the leader for synchronous operations. The just-bash adapter exposes a structural filesystem interface and adds no just-bash runtime dependency. Pass the adapter to your installed just-bash version's filesystem option.

Protected volumes

Core deliberately refuses volumes with reserved protection markers unless a storage factory is supplied. Legacy JavaScript { encryption: ... } options also fail explicitly. Encryption, keys, protected archives and migration belong to @frachter-app/opfs-vfs-premium; moving imports does not require erasing existing volumes.

License

MIT, copyright Bastian Kistner.