llms.txt
Compare with other sites' llms.txt files →# use-fs
> use-fs is a React hook for the File System Access API and the origin private file system (OPFS). Point `useFs()` at a folder the user picks on disk, or at browser-private storage, and the component receives every file inside it as a `Map<string, string>` and re-renders when a file is added, changed or deleted. It can also write, create and delete files. Nothing is uploaded; there is no server.
- [AGENTS.md](https://use-fs.com/AGENTS.md): how a coding agent should use the hook
- [Live demo](https://use-fs.com/): open a folder or browser storage and watch events stream in
- [Source on GitHub](https://github.com/TimMikeladze/use-fs)
- [Package on npm](https://www.npmjs.com/package/use-fs)
A React hook for integrating with the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API) and the [origin private file system](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Visit [**use-fs.com**](https://use-fs.com) to try it out in your browser.
Point the hook at a directory and it watches everything inside it, re-rendering when a file is added, changed or deleted. That directory can be either of two things:
- **A folder on disk**, chosen by the user through the directory picker. Read, write and manage real files directly, with no repeated file dialogs and nothing uploaded anywhere.
- **The origin private file system (OPFS)**, a private store scoped to your origin. No picker, no permission prompt, and it works in every modern browser.
Both are the same `FileSystemDirectoryHandle` underneath, so they are the same hook, the same `files` map and the same writes - only the backing store changes.
> Note: The directory picker is desktop Chrome, Edge and Opera only - check `isBrowserSupported`. OPFS works in every current browser - check `isOpfsSupported`, and `isOpfsWritable` before writing from the main thread. See [which store to use](#picker-or-opfs).
## Install
```console
npm install use-fs
yarn add use-fs
pnpm add use-fs
```
## Getting Started
```tsx
import { useFs } from "use-fs";
function App() {
const {
onDirectorySelection,
files,
isBrowserSupported,
onClear,
isProcessing,
writeFile,
deleteFile,
startPolling,
stopPolling,
isPolling,
error,
} = useFs({
// Called when new files appear in a watched directory.
onFilesAdded: (newFiles, previousFiles) => {
// newFiles: Map<string, string> - path -> contents
// previousFiles: Map<string, string> - the state before this change
console.log("Files added:", newFiles);
},
// Called when a watched file's contents change.
onFilesChanged: (changedFiles, previousFiles) => {
console.log("Files changed:", changedFiles);
},
// Called when a watched file disappears. The map holds its last contents.
onFilesDeleted: (deletedFiles, previousFiles) => {
console.log("Files deleted:", deletedFiles);
},
});
if (!isBrowserSupported) {
return <div>Browser not supported</div>;
}
return (
<div>
<button onClick={() => onDirectorySelection()}>Select Directory</button>
<button onClick={onClear}>Clear</button>
<button onClick={startPolling} disabled={isPolling}>
Start Polling
</button>
<button onClick={stopPolling} disabled={!isPolling}>
Stop Polling
</button>
<div>Status: {isPolling ? "Polling Active" : "Polling Stopped"}</div>
{error && <div role="alert">{error.message}</div>}
{Array.from(files.entries()).map(([path, content]) => (
<div key={path}>
<h3>{path}</h3>
<pre>{content}</pre>
<button onClick={() => writeFile(path, "New content")}>Save</button>
<button onClick={() => deleteFile(path)}>Delete</button>
</div>
))}
</div>
);
}
```
Paths are POSIX-style and always prefixed with the name of the watched root directory, e.g. `my-project/src/index.ts`. Every path passed to `writeFile`, `createFile`, `deleteFile` and `deleteDirectory` must resolve inside a watched directory; `.` and `..` segments are rejected.
## Picker or OPFS?
Same hook, same `files` map, same writes. What differs is who owns the bytes and what the browser asks the user first.
| | Folder on disk | Browser storage (OPFS) |
| --- | --- | --- |
| Entry point | `onDirectorySelection()`, or `addDirectory(handle)` | `addOpfsDirectory()` |
| Support flag | `isBrowserSupported` | `isOpfsSupported` (read), `isOpfsWritable` (write) |
| Browsers | Chrome, Edge, Opera - desktop only | Read: Chrome 86+, Safari 15.2+, Firefox 111+. Write from the hook: Chrome 86+, Safari 26+, Firefox 111+ |
| The user sees | A picker, then a permission prompt on first write | Nothing at all |
| User gesture | Required - call it from an event handler | Not required - an effect is fine |
| Where the bytes are | Real files, wherever the user pointed you | A private store scoped to your origin |
| Readable by other apps | Yes - their editor, their terminal, their backups | No - only this origin, only through the API |
| Across a reload | Contents survive; access does not. Re-prompt, or persist the handle in IndexedDB | Both survive. Mount it again and it is all there |
| Cleared by | The user, in their own file manager | Clearing site data, or eviction under storage pressure |
| Capacity | The disk | A quota. `navigator.storage.estimate()` reports it |
| Changed behind your back | Constantly - that is the point | Only by your own workers or another tab |
**Reach for the picker** when the files are the user's and they already care about them: an editor, a linter, a local-first tool that has to interoperate with git and the rest of their machine.
**Reach for OPFS** when the files are your app's: a cache, a scratch workspace, a WASM database, drafts that should survive a reload. Also when you simply need the feature to exist in Safari and Firefox.
Nothing forces the choice - the two are watched by the same hook, so you can offer both and let support decide:
```tsx
const {
isBrowserSupported,
isOpfsSupported,
onDirectorySelection,
addOpfsDirectory,
directories,
} = useFs();
<button onClick={() => onDirectorySelection()} disabled={!isBrowserSupported}>
Open a folder
</button>
<button onClick={() => addOpfsDirectory({ name: "workspace" })} disabled={!isOpfsSupported}>
Use browser storage
</button>
// Both roots land here, and `files` spans them.
<p>Watching: {directories.join(", ") || "nothing yet"}</p>
```
## Origin private file system
`addOpfsDirectory()` watches the origin private file system instead of a folder on disk. There is no picker, no permission prompt and no user gesture requirement, so it can be called straight from an effect - and it works in Safari and Firefox, which have no directory picker at all.
```tsx
import { useEffect } from "react";
import { useFs } from "use-fs";
function Notes() {
const { files, addOpfsDirectory, isOpfsSupported, writeFile } = useFs({
// Nothing outside this tab writes to OPFS unless a worker or another tab
// does, so drive scans by hand when you own every write.
autoStartPolling: false,
});
useEffect(() => {
if (isOpfsSupported) {
// Mounts <opfs>/notes, creating it if it does not exist.
addOpfsDirectory({ name: "notes" });
}
}, [isOpfsSupported, addOpfsDirectory]);
return (
<button onClick={() => writeFile("notes/todo.md", "buy milk")}>
Save ({files.size} files)
</button>
);
}
```
Everything the hook does works the same way against an OPFS mount: filters, `refresh`, polling, `writeFile`, `createFile`, `deleteFile`, `deleteDirectory`. Both stores can be watched at once - `addOpfsDirectory()` and `onDirectorySelection()` add roots to the same `directories` list.
| Option | Default | Description |
| --- | --- | --- |
| `name` | – | Subdirectory of the OPFS root to mount, e.g. `notes` or `notes/2026` |
| `create` | `true` | Create that subdirectory when it does not exist |
| `path` | `name`, else `"opfs"` | Path the mount is exposed under |
**Pass `name`.** The OPFS root is shared by everything on the origin - SQLite WASM journals, Emscripten scratch files, other libraries - so mounting it whole means walking all of that on every scan. A named subdirectory is yours alone.
Worth knowing:
- Contents survive a reload and are private to the origin. The user can wipe them by clearing site data, and the browser may evict them under storage pressure - call `navigator.storage.persist()` to ask for protection.
- Changes are detected from `lastModified` and `size`. OPFS writes are fast enough that a same-size rewrite inside a single millisecond can be missed, which only matters for writes coming from a worker or another tab - writes made through the hook update state directly.
- The hook writes through `createWritable`, which needs Chrome 86+, Safari 26+ or Firefox 111+. Older Safari can read OPFS but only write it from a worker - `isOpfsWritable` is `false` there and `writeFile` rejects with a `NotSupportedError`. Watching still works; see [Working alongside a worker](#working-alongside-a-worker).
- Quota is finite. A write that exceeds it rejects with `QuotaExceededError`, surfaced through `error` and `onError`. `navigator.storage.estimate()` reports the headroom.
### Working alongside a worker
`createSyncAccessHandle()` is OPFS's fast path - synchronous, in-place reads and writes, and the only way SQLite WASM and similar get native-like speed. It is worker-only, so it is not something the hook uses. The two split the work:
- **The worker owns the bytes.** It opens sync access handles and does the heavy I/O.
- **The hook watches the results.** Mount the directory the worker writes into; changes appear on the next poll after the worker calls `flush()` or `close()` on its handle.
```ts
// worker.ts
const root = await navigator.storage.getDirectory();
const dir = await root.getDirectoryHandle("exports", { create: true });
const file = await dir.getFileHandle("report.json", { create: true });
const handle = await file.createSyncAccessHandle();
handle.truncate(0);
handle.write(new TextEncoder().encode(JSON.stringify(report)));
handle.flush();
handle.close();
```
```tsx
// Component - sees exports/report.json within one poll of the worker closing it.
const { files, addOpfsDirectory } = useFs();
useEffect(() => {
addOpfsDirectory({ name: "exports" });
}, [addOpfsDirectory]);
```
Things to know:
- **Keep databases out of the watched tree.** A database a worker writes to changes on nearly every poll. Mount a directory the database is not in, or opt into `binaryFilter` - `useFs({ filters: [...commonFilters, binaryFilter] })` - which skips `.sqlite`, `.db`, their `-wal` / `-shm` / `-journal` files, `.wasm` and other binary files.
- **Sync access handles are exclusive.** While a worker holds one, `writeFile`, `deleteFile` and `deleteDirectory` on that file reject with an error named `NoModificationAllowedError` whose message names the path - check it with `isLockedError(error)` and retry after the worker closes the handle.
- **A locked file keeps its last known contents.** If reading it fails during a scan, it is reported through `onError` once - not on every poll - and the error is reported again only if it fails again after a clean read.
`getOpfsRoot()`, `isOpfsSupported()` and `isOpfsWritable()` are exported too, for reaching the handle directly - `(await getOpfsRoot({ name: "notes" })).removeEntry("todo.md")`.
## How watching works
The hook re-scans every watched directory on an interval:
1. The tree is walked breadth-first with a bounded number of directories open at once. Filters that reject a directory prune the whole subtree, so `node_modules` is never enumerated.
2. Each discovered file is stat'd. Contents are only re-read when `lastModified` or `size` changed, so a steady-state poll over a large tree does no content I/O.
3. Added, changed and deleted files are diffed against the previous scan and reported through the callbacks. Rendered state updates are coalesced by `debounceInterval`; callbacks always fire immediately.
Scans never throw. A directory that cannot be enumerated (revoked permission, removed mid-scan) or a file that cannot be read (locked by a worker) keeps its last known contents instead of being reported as deleted, and the error is surfaced through `error` and `onError` - once per file until it reads cleanly again.
## Permissions
`onDirectorySelection` requests `mode: "read"` by default. Writing prompts for `readwrite` access the first time it is needed, which requires a user gesture - so call `writeFile` from an event handler. To get write access up front, pass `mode: "readwrite"`:
```tsx
const fs = useFs({ mode: "readwrite" });
```
OPFS needs none of this: an OPFS handle carries no permission at all, so `addOpfsDirectory` and every write against it work without a prompt or a gesture.
`addDirectory` accepts a handle directly, which is how you restore access across sessions after persisting a handle in IndexedDB:
```tsx
const handle = await loadHandleFromIndexedDb();
if ((await handle.queryPermission({ mode: "read" })) === "granted") {
await fs.addDirectory(handle);
}
```
The handle's own name is the path it is watched under. Pass `path` to override it, which a handle with no name - the OPFS root is the one that occurs in practice - requires:
```tsx
await fs.addDirectory(handle, { path: "storage" });
```
## Filters
A filter decides which entries are visible to the hook. `commonFilters` (the default) prunes build output, drops OS scratch files and honours every `.gitignore` in the tree.
```tsx
import { commonFilters, createFilter, useFs } from "use-fs";
const onlyTypeScript = createFilter({
shouldIncludeFile: ({ name }) => name.endsWith(".ts") || name.endsWith(".tsx"),
});
useFs({ filters: [...commonFilters, onlyTypeScript] });
```
Every callback receives a context object rather than a bare path:
| Field | Description |
| --- | --- |
| `path` | Full path including the watched root, e.g. `my-project/src/index.ts` |
| `rootPath` | Path of the watched root, e.g. `my-project` |
| `relativePath` | Path relative to the watched root, e.g. `src/index.ts` |
| `name` | Name of the entry, e.g. `index.ts` |
Filters may also implement `onDirectoryEnter`, which runs before any of a directory's entries are tested - that is how `gitFilter` loads a `.gitignore` before deciding anything in its directory.
Built-in filters:
- `distFilter` - prunes `node_modules`, `dist`, `build`, `out`, `vendor`, `coverage`, `.next`, `.nuxt`, `.turbo`, `.cache`, `.output`, `.svelte-kit`, `.parcel-cache`
- `miscFilter` - drops `.DS_Store`, `Thumbs.db`, `desktop.ini` and `*.crswap`
- `binaryFilter` - opt in, not part of `commonFilters`. Drops binary files by case-insensitive suffix (`DEFAULT_BINARY_FILE_SUFFIXES`): SQLite databases and their `-wal` / `-shm` / `-journal` files, `.wasm`, archives, images, audio, video, fonts and `.pdf`. Worth adding when a worker writes a database into a watched directory - otherwise each write means re-reading the whole file as text
- `gitFilter` - honours nested `.gitignore` files and always skips `.git`
- `commonFilters` - `distFilter`, `miscFilter` and `gitFilter`
Builders: `createFilter`, `createExcludedDirectoryFilter`, `createExcludedFileFilter`.
### Options
| Option | Default | Description |
| --- | --- | --- |
| `filters` | `commonFilters` | Filters applied while walking watched directories |
| `onFilesAdded` | – | Called with files seen for the first time |
| `onFilesChanged` | – | Called with files whose contents changed |
| `onFilesDeleted` | – | Called with files that disappeared, mapped to their last known contents |
| `onError` | – | Called for every recoverable error |
| `pollInterval` | `300` | Delay between scans, in milliseconds |
| `debounceInterval` | `50` | How long rendered state updates are coalesced. `0` updates synchronously |
| `batchSize` | `50` | Maximum number of files read concurrently |
| `concurrency` | `8` | Maximum number of directories enumerated concurrently |
| `mode` | `"read"` | Access level requested when opening the picker |
| `autoStartPolling` | `true` | Start polling as soon as a directory is added |
| `processingIndicatorDelay` | `100` | How long a scan must run before `isProcessing` flips to `true` |
Options are read at the moment they are used, so inline callbacks and filter arrays never need to be memoized.
### Return values
| Value | Description |
| --- | --- |
| `files: Map<string, string>` | Watched files, keyed by path |
| `handles: Map<string, FileSystemFileHandle>` | File handles, keyed by path |
| `directories: string[]` | Paths of the watched root directories |
| `isProcessing: boolean` | Whether a scan has been running long enough to be worth showing |
| `isPolling: boolean` | Whether the hook is polling for changes |
| `isBrowserSupported: boolean` | Whether the directory picker is available |
| `isOpfsSupported: boolean` | Whether the origin private file system is available |
| `isOpfsWritable: boolean` | Whether `writeFile` / `createFile` can write to OPFS (`false` in Safari before 26) |
| `error: Error \| null` | The most recent recoverable error |
| `onDirectorySelection(options?)` | Opens the picker and watches the chosen directory. Resolves to its path, or `null` if the picker was dismissed |
| `addDirectory(handle, options?)` | Watches an existing handle. Resolves to the path it is exposed under |
| `addOpfsDirectory(options?)` | Watches the origin private file system. Resolves to the path it is exposed under |
| `removeDirectory(path)` | Stops watching a directory without touching disk |
| `onClear()` | Stops watching everything and resets the hook |
| `refresh()` | Runs a scan immediately |
| `startPolling()` / `stopPolling()` | Manual control over the polling loop |
| `writeFile(path, data, options?)` | Writes to a file, creating it and any missing parents by default |
| `createFile(path, initialData?)` | Creates (or opens) a file and returns its handle |
| `deleteFile(path)` | Deletes a file |
| `deleteDirectory(path)` | Deletes a directory and everything below it |
| `requestPermission(mode?)` | Requests access for every watched directory |
`writeFile` replaces the file's contents by default. Pass `{ truncate: false }` to write over the existing bytes from offset `0` and keep anything trailing, or `{ create: false }` to fail instead of creating a missing file.
### Lower-level exports
`walkDirectory`, `scanDirectories`, `toContentMap`, `normalizePath`, `isFileSystemAccessSupported`, `isOpfsSupported`, `isOpfsWritable`, `isLockedError`, `getDirectoryPicker`, `getOpfsRoot` and `ensurePermission` are exported for building on top of the same primitives the hook uses.