It is very common for an application to interact with local files. For example, a general workflow is opening a file, making some changes, and saving the file. For web apps, this might be hard to implement. It is possible to simulate the file operations using IndexedDB API, an HTML input element with the file type, an HTML anchor element with the download attribute, etc, but that would require a good understanding of these standards and careful design for a good user experience. Also, the performance may not be satisfactory for frequent operations and large files.

The File System Access API makes it possible for web apps to have easy and efficient file access. It provides a way to create, open, read, and write files directly. It also allows apps to create directories and enumerate their contents.

Origin Private File System

WebKit has added support for the File System Access API with the origin private file system — a private storage endpoint to some origin. Conceptually, every origin owns an independent directory, and a page can only access files or directories in its origin’s directory. For example, https://webkit.org cannot read files created by https://apple.com.

Based on the implementation of different browsers, one entry in the origin private file system does not necessarily map to an entry in the user’s local filesystem — it can be an object stored in some database. That means a file or directory created via the File System Access API may not be easily retrieved from outside of the browser.

Persistence

The API is currently unavailable for Safari windows in Private Browsing mode. For where is it available, its storage lifetime is the same as other persistent storage types like IndexedDB and LocalStorage. The storage policy will conform to the Storage Standard. Safari users can view and delete file system storage for a site via Preferences on macOS or Settings on iOS.

Browser Support

The File System Access API with origin private file system is enabled in WebKit from r284131. It is available in Safari on:

• macOS 12.2 and above
• iOS 15.2 and above

In Safari on macOS 12.4 and iOS 15.4, we introduced the getFile() method of FileSystemFileHandle.

The API

WebKit currently supports four interfaces of the File System Access API:

• FileSystemHandle, which represents an entry in the file system. It is available in Worker and
• FileSystemFileHandle, which inherits from FileSystemHandle and represents a file entry.
• FileSystemDirectoryHandle, which inherits from FileSystemHandle and represents a directory entry.
• FileSystemSyncAccessHandle, which provides an exclusive duplex stream for synchronous read and write on an entry. Unlike the interfaces above, which exist in both Window and Worker contexts, FileSystemSyncAccessHandle is only available in Worker.

With these basic interfaces in mind, let’s look at how to use them by diving into some examples.

Examples

Accessing the Origin Private File System

In the origin private file system, a FileSystemHandle represents either the root directory of the origin’s space, or a descendant of the root directory. Therefore, the first step is to get the root FileSystemDirectoryH