July 13, 2025By Jun Nguyen4 min read876 words

OPFS

Technology

What Is OPFS?

The Origin Private File System (OPFS) is a browser-native storage API that gives web applications access to a high-performance, sandboxed, origin-specific virtual filesystem. Unlike IndexedDB or LocalStorage, which are key-value stores, OPFS provides granular, low-level file operations—think byte-by-byte access, file streaming, and in-place writes, much closer to what you’d expect from a native filesystem.

Key Features

Origin-Scoped & Private: Files are isolated per origin (domain + protocol + port) and are not visible to the user or accessible by other origins.
Performance: OPFS is significantly faster (3x–4x compared to IndexedDB for many operations) and supports in-place updates, making it ideal for large files or databases (e.g., SQLite in WASM).
No User Prompts: Unlike the File System Access API, OPFS doesn’t require permission prompts or security checks for each file operation, as all data stays within the origin’s sandbox.
Synchronous Access in Workers: The most performant synchronous methods (e.g.,
read()
,
write()
) are only available inside Web Workers, not on the main thread, to avoid blocking UI rendering.
Quota-Limited: Storage is subject to browser quotas, similar to IndexedDB. If you hit the limit, a
QuotaExceededError
is thrown.
Persistence & Eviction: Data is persisted to disk, but can be evicted if the user clears site data or the browser needs space.

Supported Browsers

OPFS is now supported in all major browsers: Chrome, Edge, Firefox, and Safari (from Safari 15.2+ and macOS 12.2+). Internet Explorer is not supported and never will be.

When to Use OPFS

OPFS is a game-changer for web apps needing native-like storage performance, such as:

Client-side databases: Running SQLite or similar databases in the browser (e.g., via WASM).
Large file manipulation: Audio/video editors, image editors (e.g., Photoshop Web), or offline media viewers.
Persistent uploads/downloads: Apps that need to cache large files for offline use or resume interrupted transfers.
Advanced caching: Games or productivity apps that need to cache and manage lots of assets efficiently.

API Usage Overview

To access OPFS:

Get the root directory:

const root = await navigator.storage.getDirectory();

Work with files and directories:
- Use
  root.getFileHandle('filename', { create: true })
  to create or open files.
- Use
  root.getDirectoryHandle('dirname', { create: true })
  for directories.
- For high-performance, use synchronous access methods inside a Web Worker:

const handle = await root.getFileHandle('myfile', { create: true });
const syncHandle = await handle.createSyncAccessHandle();// Use syncHandle.read(), syncHandle.write(), etc.

Limitations & Gotchas

Main Thread Restrictions: Synchronous file access is only available in Web Workers, not on the main thread or in iframes.
Quota Management: There’s no hard size limit, but browsers may enforce quotas dynamically. Always handle
QuotaExceededError
gracefully.
No User File Visibility: Files stored in OPFS are not accessible to the user outside the browser, nor are they mapped to visible files on disk.
Concurrency: OPFS does not handle concurrent access between tabs or workers. You must manage this yourself, e.g., via a SharedWorker.

Real-World Usage

Photoshop Web uses OPFS to manage large PSD files and cache operations efficiently, enabling near-native performance in the browser.
SQLite in WASM leverages OPFS for fast, persistent database storage in web applications.

Summary Table: OPFS vs. Other Web Storage

Feature	OPFS	IndexedDB	File System Access API
Performance	High (native-like)	Medium	Low–Medium
File Granularity	Byte-level, streaming	Key-value blobs	File-level (user visible)
User Prompts	None	None	Yes (for user files)
Synchronous Access	Workers only	No	No
Storage Quota	Yes	Yes	N/A (user files)
User File Visibility	No	No	Yes