The File System Observer API origin trial

Thomas Steiner

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.
• Experiences that profit from hot-reloading, like HTML-based slide decks where a reload gets triggered by a file change.

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.
}

Note: See the Explainer for general approaches to polyfill the behavior of the File System Observer API through polling.

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 (a FileSystemHandle): The handle passed to the FileSystemObserver.observe() function.
• changedHandle (a FileSystemHandle): The handle affected by the file system change. This field will be null for "errored", "unknown", and "disappeared" type events. To see which file or directory has disappeared, use relativePathComponents.
• relativePathComponents (an Array): The path of the changedHandle relative to the root.
• type (a String): The type of the change. The following types are possible:
  • "appeared": The file or directory was created or got moved into the root.
  • "disappeared": The file or directory was deleted or got moved out of the root.
  • "modified": The file or directory was modified.
  • "moved": The file or directory was moved within the root.
  • "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. This value will also be sent when the maximum limit of per-origin observations is reached. This limit is dependent on the operating system and not known beforehand. If this happens, the site may decide to retry, though there's no guarantee that the operating system has freed up enough resources. Another case for when this value will be sent is when the observed handle (that is, the root of the observation) is deleted or moved. In this case, first, the "disappeared" event is sent, followed by an "errored" event, indicating that the observation is no longer valid. Finally, this event is sent when permission to the directory or file handle is removed.
• relativePathMovedFrom (an Array, optional): The former location of a moved handle. Available only when the type is "moved".

Note: Depending on the operating system, not all change events may be reported with the same level of detail, for example, when the contents of a directory change recursively. At best, the website will receive a detailed change record containing the type of change and a handle to the affected path. At worst, the website receives a more generic change record (that is, a type with the value "unknown") that still requires the website to enumerate the directory to figure out which child changed. This is still an improvement over polling, since the directory enumeration can be kicked off on-demand from the callback function, rather than needing to poll for changes in intervals.

Note: On Windows "moved" events aren't supported between directories. They are reported as a "disappeared" from the source directory and an "appeared" in the destination directory. They are reported as "moved" when the source and destination are in the same directory.

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);

Note: The unobserve() method is not supported. Use the disconnect() method as a workaround. If you're interested in progress on this feature, star the feature bug.

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

• Explainer
• TAG review
• Mozilla Standards Position
• WebKit Standards Position
• ChromeStatus
• Chromium bug

Acknowledgements

This document was reviewed by Daseul Lee, Nathan Memmott, Etienne Noël, and Rachel Andrew.