Thomas Steiner

TheFile System Access API and theOrigin 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 theorigin of each site and that comes with certain performance advantages. The way developers interact with files and directories in both cases is throughFileSystemHandle objects, more concretely,FileSystemFileHandle for files, andFileSystemDirectoryHandle 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 thelastModified 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'inself){// The File System Observer API is supported.}

Initialize a file system observer

Initialize a File System Observer by callingnew FileSystemObserver(), providing it acallback function as an argument.

constobserver=newFileSystemObserver(callback);

Start observing a file or directory

To begin observing a file or directory, call the asynchronousobserve() method of theFileSystemObserver instance. Provide this method theFileSystemHandle of the selected file or directory as an argument. When observing a directory, there's an optionaloptions argument that lets you choose if you want to be informed of changes to the directory recursively (that is, for the directory itself andall contained subdirectories and files). The default option is to only observe the directory itself and the directly contained files.

// Observe a file.awaitobserver.observe(fileHandle);// Observe a directory.awaitobserver.observe(directoryHandle);// Observe a directory recursively.awaitobserver.observe(directoryHandle,{recursive:true});

The callback function

When changes to the file system happen, a callback function is called with thefile system changerecords and theobserver itself as its arguments. You can use theobserver argument to, for example, disconnect the observer (seeStop observing the file system) when the files you're interested in are all deleted.

constcallback=(records,observer)=>{for(constrecordofrecords){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. This field will benull for"errored","unknown", and"disappeared" type events. To see which file or directory has disappeared, userelativePathComponents.
• 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 tostop 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 (anArray, optional): The former location of a moved handle. Available only when thetype is"moved".

observer.unobserve(fileHandle);

Stop observing the file system

To stop observing the file system, disconnect theFileSystemObserver instance as follows.

observer.disconnect();

Try the API

To test the File System Observer API locally, set the#file-system-observer flag inabout:flags. To test the API with real users,sign up for the origin trial and follow the instructions as per the guideChrome 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 embeddeddemo. Check out thesource code. 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 ascreenshot of the demo.

Feedback

If you have feedback on the shape of the File System Observer API, comment onIssue #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 byDaseul Lee,Nathan Memmott,Etienne Noël, andRachel Andrew.