Motivation
Why OPFS VFS exists
We needed browser applications to work with many files, keep them across sessions, and access them synchronously. We built OPFS VFS so each application would not have to build its own filesystem.
More files than available handles
The first obstacle was a database. During development, PGlite's OPFS access handle pool could not run in macOS Safari. The browser's limit on open synchronous handles was below what a standard Postgres installation needed.
Memory-only storage could not keep the database across sessions. PGlite's IndexedDB backend could, but it keeps database files in RAM and saves whole changed files. A small update to a large file can therefore require a large write. That is a property of this backend, not a limit of every IndexedDB application.
We wanted persistent file access without tying the number of application files to the number of native handles. That became the starting point for OPFS VFS.
Build the filesystem once
OPFS VFS packs logical files into a volume backed by a bounded set of OPFS handles. Applications use paths, directories, and file operations. The library manages the storage layout, allocation, metadata, and recovery.
File operations run synchronously inside a dedicated worker, which suits databases and WebAssembly runtimes. An asynchronous worker client lets the page use the same filesystem without blocking its interface.
Browser limits have changed since we started. PGlite's access handle pool completed our published iPhone Safari runs. OPFS VFS still offers a different storage layout and a choice of memory or disk buffering. The right backend depends on the application; our benchmarks and storage guide make those tradeoffs explicit.
Persistence is local to a browser and origin. Applications still need deliberate save points and a way to back up important work.
Work with files you can inspect
A common filesystem also gives applications common tools. The PGlite adapter stores database files in a volume. The just-bash adapter brings shell commands and scripts to workspace files.
We built Volume Explorer to browse, preview, and edit those files while an application runs. Developers can inspect a path directly instead of decoding an application's private chunking scheme.
The local AI demo uses the same approach. A model works with documents through file paths and shell operations, and you can inspect its changes in the explorer.
Add capabilities with plugins
Protecting stored files was another requirement. Our premium encryption plugin adds encrypted volumes with passkey-based access. Encryption is a separate extension, not a feature of the core package.
The community subscription plugin reports file changes, including edits made by AI tools. Applications can reread affected paths to refresh their interface. A premium cloud sync plugin is planned to connect local volumes with backend cloud storage.