FileSystemObserver

Constructor

FileSystemObserver()

Creates a new FileSystemObserver object instance.

Instance methods

disconnect()

Stop observing the filesystem.

observe()

Start observing changes to a given file or directory.

Examples

Initialize a FileSystemObserver

Before you can start observing file or directory changes, you need to initialize a FileSystemObserver to handle the observations. This is done using the FileSystemObserver() constructor, which takes a callback function as an argument:

const observer = new FileSystemObserver(callback);

The callback function body can be specified to return and process file change observations in any way you want:

const callback = (records, observer) => {
  for (const record of records) {
    console.log("Change detected:", record);
    const reportContent = `Change observed to ${record.changedHandle.kind} ${record.changedHandle.name}. Type: ${record.type}.`;
    sendReport(reportContent); // Some kind of user-defined reporting function
  }

  observer.disconnect();
};

Observe a file or directory

Once a FileSystemObserver instance is available, you can start observing changes to a file system entry by calling the FileSystemObserver.observe() method.

You can observe a file or directory in the user-observable file system or the Origin Private File System (OPFS) by passing a FileSystemFileHandle or FileSystemDirectoryHandle to observe(). Instances of these objects can be returned, for example, when asking the user to select a file or directory using Window.showSaveFilePicker() or Window.showDirectoryPicker():

// Observe a file
async function observeFile() {
  const fileHandle = await window.showSaveFilePicker();

  await observer.observe(fileHandle);
}

// Observe a directory
async function observeDirectory() {
  const directoryHandle = await window.showDirectoryPicker();

  await observer.observe(directoryHandle);
}

You can also observe changes to the OPFS by passing a FileSystemSyncAccessHandle to observe():

// Observe an OPFS file system entry
async function observeOPFSFile() {
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  const syncHandle = await draftHandle.createSyncAccessHandle();

  await observer.observe(syncHandle);
}

Stop observing the file system

When you want to stop observing changes to the file system entry, you can call FileSystemObserver.disconnect():

observer.disconnect();

Specifications

Not currently part of a specification. See https://github.com/whatwg/fs/pull/165 for the relevant specification PR.

Browser compatibility

See also

• File System API
• The File System Observer API origin trial on developer.chrome.com (2024)