Theobserve() method of theFileSystemObserver interface asks the observer to start observing changes to a given file or directory.

Syntax

observe(handle)observe(handle, options)

Parameters

handle

The handle of the file system entry representing the file or directory to observe.

• For the user-observable file system, this can be aFileSystemFileHandle or aFileSystemDirectoryHandle.
• For theOrigin Private File System (OPFS), it can be aFileSystemFileHandle, aFileSystemDirectoryHandle, or aFileSystemSyncAccessHandle.

optionsOptional

An object specifying options for theobserve() call. This can contain the following properties:

recursive

A boolean specifying whether you want to observe changes to a directory recursively. If set totrue, changes are observed in the directory itself and all contained subdirectories and files. If set tofalse, changes are only observed in the directory itself and directly contained files (that is, files in subdirectories are excluded). Defaults tofalse.

This property has no effect ifhandle represents a file.

Return value

APromise that resolves toundefined.

Exceptions

NotFoundErrorDOMException

Thrown if the file or directory represented byhandle could not be found.

Examples

Observe a file or directory

Assuming aFileSystemObserver instance is available, you can start observing changes to a file system entry by callingobserve().

You can observe a file or directory in the user-observable file system or theOrigin Private File System (OPFS) by passing aFileSystemFileHandle orFileSystemDirectoryHandle toobserve(). Instances of these objects can be returned, for example, when asking the user to select a file or directory usingWindow.showSaveFilePicker() orWindow.showDirectoryPicker():

// Observe a fileasync function observeFile() {  const fileHandle = await window.showSaveFilePicker();  await observer.observe(fileHandle);}// Observe a directoryasync function observeDirectory() {  const directoryHandle = await window.showDirectoryPicker();  await observer.observe(directoryHandle);}

You can also observe changes to the OPFS by passing aFileSystemSyncAccessHandle toobserve():

// Observe an OPFS file system entryasync 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);}

Observe a directory recursively

To observe a directory recursively, callobserve() with therecursive option set totrue:

// Observe a directory recursivelyasync function observeDirectory() {  const directoryHandle = await window.showDirectoryPicker();  await observer.observe(directoryHandle, { recursive: true });}

Specifications

Not currently part of a specification. Seehttps://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)