The origin private file system

The File System Standard introduces an origin private file system (OPFS) as a storage endpoint private to the origin of the page and not visible to the user that provides optional access to a special kind of file that is highly optimized for performance.

Thomas Steiner

Browser support

The origin private file system is supported by modern browsers and is standardized by the Web Hypertext Application Technology Working Group (WHATWG) in the File System Living Standard.

Motivation

When you think of files on your computer, you probably think about a file hierarchy: files organized in folders that you can explore with your operating system's file explorer. For example, on Windows, for a user called Tom, their To Do list might live in C:\Users\Tom\Documents\ToDo.txt. In this example, ToDo.txt is the filename, and Users, Tom, and Documents are folder names. `C:` on Windows represents the root directory of the drive.

Traditional way of working with files on the web

To edit the To Do list in a web application, this is the usual flow:

1. The user uploads the file to a server or opens it on the client with <input type="file">.
2. The user makes their changes, and then downloads the resulting file with an injected <a download="ToDo.txt> that you programmatically click() via JavaScript.
3. For opening folders, you use a special attribute in <input type="file" webkitdirectory>, which, despite its proprietary name, has practically universal browser support.

Modern way of working with files on the web

This flow is not representative of how users think of editing files, and means users end up with downloaded copies of their input files. Therefore, the File System Access API introduced three picker methods—showOpenFilePicker(), showSaveFilePicker(), and showDirectoryPicker()—that do exactly what their name suggests. They enable a flow as follows:

1. Open ToDo.txt with showOpenFilePicker(), and get a FileSystemFileHandle object.
2. From the FileSystemFileHandle object, get a File by calling the file handle's getFile() method.
3. Modify the file, then call requestPermission({mode: 'readwrite'}) on the handle.
4. If the user accepts the permission request, save the changes back to the original file.
5. Alternatively, call showSaveFilePicker() and let the user pick a new file. (If the user picks a previously opened file, its contents will be overwritten.) For repeat saves, you can keep the file handle around, so you don't have to show the file save dialog again.

Restrictions of working with files on the web

Files and folders that are accessible via these methods live in what can be called the user-visible file system. Files saved from the web, and executable files specifically, are marked with the mark of the web, so there's an additional warning the operating system can show before a potentially dangerous file gets executed. As an additional security feature, files obtained from the web are also protected by Safe Browsing, which, for the sake of simplicity and in the context of this article, you can think of as a cloud-based virus scan. When you write data to a file using the File System Access API, writes are not in-place, but use a temporary file. The file itself is not modified unless it passes all these security checks. As you can imagine, this work makes file operations relatively slow, despite improvements applied where possible, for example, on macOS. Still every write() call is self-contained, so under the hood it opens the file, seeks to the given offset, and finally writes data.

Files as the foundation of processing

At the same time, files are an excellent way to record data. For example, SQLite stores entire databases in a single file. Another example are mipmaps used in image processing. Mipmaps are pre-calculated, optimized sequences of images, each of which is a progressively lower resolution representation of the previous, which makes many operations like zooming faster. So how can web applications get the benefits of files, but without the performance costs of web-based file processing? The answer is the origin private file system.

The user-visible versus the origin private file system

Unlike the user-visible file system browsed using the operating system's file explorer, with files and folders you can read, write, move, and rename, the origin private file system is not meant to be seen by users. Files and folders in the origin private file system, as the name suggests, are private, and more concretely, private to the origin of a site. Discover the origin of a page by typing location.origin in the DevTools Console. For example, the origin of the page https://developer.chrome.com/articles/ is https://developer.chrome.com (that is, the part /articles is not part of the origin). You can read more about the theory of origins in Understanding "same-site" and "same-origin". All pages that share the same origin can see the same origin private file system data, so https://developer.chrome.com/docs/extensions/mv3/getstarted/extensions-101/ can see the same details as the previous example. Each origin has its own independent origin private file system, which means the origin private file system of https://developer.chrome.com is completely distinct from the one of, say, https://web.dev. On Windows, the root directory of the user-visible file system is C:\\. The equivalent for the origin private file system is an initially empty root directory per origin accessed by calling the asynchronous method navigator.storage.getDirectory(). For a comparison of the user-visible file system and the origin private file system, see the following diagram. The diagram shows that apart from the root directory, everything else is conceptually the same, with a hierarchy of files and folders to organize and arrange as needed for your data and storage needs.