The File System Access API and the Origin Private File System API both allow developers to access files and directories on the user's device. The former lets developers read and write to the regular, user-visible file system, and the latter opens up a special, hidden from the user file system that is private to the origin of each site and that comes with certain performance advantages. The way developers interact with files and directories in both cases is through FileSystemHandle
objects, more concretely, FileSystemFileHandle
for files, and FileSystemDirectoryHandle
for directories. Up until now, being informed of changes to a file or directory in either of the file systems required some form of polling and comparing the lastModified
timestamp or even the file contents itself.
The File System Observer API, in origin trial from Chrome 129, changes that, and lets developers be alerted automatically when changes happen. This guide explains how it works and how to try the feature.
Use cases
Use the File System Observer API in apps that need to be informed of possible file system changes as soon as they happen.
- Web-based integrated development environments (IDEs) that show a representation of a project's file system tree.
- Apps that synchronize file system changes with a server. For example, a SQLite database file.
- Apps that need to notify the main thread of file system changes from a worker or another tab.
- Apps that observe a directory of resources, for example, to automatically optimize images.
How to use the File System Observer API
Feature detection
To see if the File System Observer API is supported, run a feature test as in the following example.
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
Initialize a file system observer
Initialize a File System Observer by calling new FileSystemObserver()
, providing it a callback
function as an argument.
const observer = new FileSystemObserver(callback);
Start observing a file or directory
To begin observing a file or directory, call the asynchronous observe()
method of the FileSystemObserver
instance. Provide this method the FileSystemHandle
of the selected file or directory as an argument. When observing a directory, there's an optional options
argument that lets you choose if you want to be informed of changes to the directory recursively (that is, for the directory itself and all contained subdirectories and files). The default option is to only observe the directory itself and the directly contained files.
// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});
The callback function
When changes to the file system happen, a callback function is called with the file system change records
and the observer
itself as its arguments. You can use the observer
argument to, for example, disconnect the observer (see Stop observing the file system) when the files you're interested in are all deleted.
const callback = (records, observer) => {
for (const record of records) {
console.log('Change detected', record);
}
};
The file system change record
Each file system change record has the following structure. All fields are read-only.
root
(aFileSystemHandle
): The handle passed to theFileSystemObserver.observe()
function.changedHandle
(aFileSystemHandle
): The handle affected by the file system change.relativePathComponents
(anArray
): The path of thechangedHandle
relative to theroot
.type
(aString
): The type of the change. The following types are possible:"appeared"
: The file or directory was created or got moved into theroot
."disappeared"
: The file or directory was deleted or got moved out of theroot
."modified"
: The file or directory was modified."moved"
: The file or directory was moved within theroot
."unknown"
: This indicates that zero or more events were missed. Developers should poll the watched directory in response to this."errored"
: The observation is no longer valid. In this case, you may want to stop observing the file system.
relativePathMovedFrom
(anArray
, optional): The former location of a moved handle. Available only when thetype
is"moved"
.
Stop observing a file or directory
To stop observing a FileSystemHandle
, call the unobserve()
method, passing it the handle as an argument.
observer.unobserve(fileHandle);
Stop observing the file system
To stop observing the file system, disconnect the FileSystemObserver
instance as follows.
observer.disconnect();
Try the API
To test the File System Observer API locally, set the #file-system-observer
flag in about:flags
. To test the API with real users, sign up for the origin trial and follow the instructions as per the guide Chrome Origin Trials. The origin trial will run from Chrome 129 (September 11, 2024) to Chrome 134 (February 26, 2025).
Demo
You can see the File System Observer API in action in the embedded demo. Check out the source code or remix the demo code on Glitch. The demo randomly creates, deletes, or modifies files in an observed directory and logs its activity in the upper part of the app window. It then logs the changes as they occur in the lower part of the app window. If you read this on a browser that doesn't support the File System Observer API, see a screenshot of the demo.
Feedback
If you have feedback on the shape of the File System Observer API, comment on Issue #123 in the WHATWG/fs repository.
Relevant links
Acknowledgements
This document was reviewed by Daseul Lee, Nathan Memmott, Etienne Noël, and Rachel Andrew.