use-fs

use-fs is a React hook that puts a real folder behind your component state. You point useFs() at a directory the user picks off their disk, or at the browser's own private storage, and the hook hands your component a map of every file inside it. When a file is added, edited, or deleted, the component re-renders. There's no upload step, no server round trip, and no second file dialog to nag the user with. The files your app is reading are the same files their editor has open.

The problem it solves is that the File System Access API is powerful and awkward at the same time. Handles, permission prompts, recursive walks, and change detection are all left to you, and most apps end up writing the same fragile directory-crawling code. use-fs wraps that into one hook with a documented scan loop, so what you write is React state rather than filesystem plumbing. The same hook also covers the origin private file system, which is a very different API in the spec but the same shape once it's behind a directory handle.

A scan runs every 300 milliseconds by default and happens in three steps. It walks the tree breadth-first with a bounded number of directories open at once, and filters run first, so a filter that rejects a directory prunes the whole subtree and node_modules never gets enumerated at all. Every discovered file gets stat'd before anything is read, and contents are re-read only when lastModified or size actually moved, which means polling a large tree that isn't changing costs no content I/O. Then added, changed, and deleted files are resolved against the previous scan. Rendered state is coalesced by a debounce interval while callbacks fire immediately, so a burst of writes doesn't turn into a burst of renders.

Failure handling is more careful than most hobby wrappers. Scans never throw. If a directory can't be enumerated because permission was revoked or the folder moved, the hook keeps its last known contents instead of reporting every file in it as deleted, and it surfaces the reason through an error value you can read. Three callbacks cover the lifecycle, one for files added, one for files changed, and one for files deleted. The delete callback still hands you the last known contents of the file, so you can archive it, undo it, or write it back. Each callback also receives the previous file map alongside the change set, which makes diffing against the last known state straightforward instead of something you have to track yourself.

Two stores sit behind the same hook. The first is a folder on disk, which needs the directory picker, so it only opens from a user gesture and asks for a write permission prompt. That path works in desktop Chrome, Edge, and Opera. The second is the origin private file system, a real directory tree scoped to your origin that the user never sees and that survives reloads. It asks for nothing, so it can mount inside an effect, and it works in Chrome, Edge, Opera, Safari 17 and later, and Firefox 111 and later. Both are a FileSystemDirectoryHandle underneath, which means the same files map, the same filters, and the same writeFile work against either one, and you can watch both at once.

The API surface is fully documented on the site. State covers the files map, the underlying handles, the watched roots, processing and polling flags, browser and OPFS support checks, and the most recent recoverable error. Actions cover opening the picker, mounting OPFS storage, adding a handle you already hold, removing a root, forcing a scan, driving the polling loop by hand, writing files with missing parents created for you, creating and deleting files and directories, re-requesting permission, and clearing everything. Options tune the filters, poll interval, debounce, batch size, concurrency, read or write mode, and whether polling starts on its own. Helpers like walkDirectory, scanDirectories, toContentMap, and createFilter are exported too, and the default commonFilters set prunes build output, drops OS scratch files, and honours every .gitignore in the tree.

It suits anyone building a browser-based editor, a local-first note or code tool, a playground, or a diffing and review interface that should read real project files rather than pasted text. Installation is one npm install use-fs, with copy-paste commands for Yarn, pnpm, Bun, and Deno on the homepage, and there's a live playground on the site that watches a folder in front of you, shows the file contents, and streams the add and delete events as each scan resolves, so you can judge it before writing any code. The library is MIT licensed, published on npm, and developed in the open on GitHub. The honest limits are browser reach and lifetime, since disk access needs a Chromium-based desktop browser and ends when the tab closes.