> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OPFS

> Virtualize the browser's Origin Private File System from the browser.

`OPFSVFS` mounts the
[Origin Private File System](https://web.dev/articles/origin-private-file-system):
files persist across page reloads and stay scoped to the page's origin. It
needs no service and no credentials; see the [OPFS page](https://docs.mirage.strukto.ai/home/setup/opfs.md).

> [!NOTE]
>
> Browser only. Node has no OPFS; for local files in Node, use
> [Disk](https://docs.mirage.strukto.ai/typescript/vfs/disk.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-browser
```

## Configure

```ts theme={null}
import { MountMode, OPFSVFS, Workspace } from '@struktoai/mirage-browser'

const opfs = new OPFSVFS({ root: 'mirage' })
const ws = new Workspace({ '/data': opfs }, { mode: MountMode.WRITE })

const result = await ws.shell('echo hello > /data/note.txt && cat /data/note.txt')
console.log(result.stdoutText)
await ws.close()
```

`capacity: '100MB'` caps the bytes the folder holds; a write past it fails with
"Disk quota exceeded". See [capacity](https://docs.mirage.strukto.ai/home/setup/vfs.md#mount-capacity). A mount
takes `MountMode.READ`, `WRITE` or `EXEC`.

### Fields

| Field | Default | Notes |
| - | - | - |
| `root` | `''` | Folder under the origin's OPFS root, so several workspaces can keep apart. Empty mounts the OPFS root itself. |
| `capacity` | none | The most bytes the folder may hold, a size like `100MB` or a count of bytes. |

## Layout

```text theme={null}
/data/
  note.txt
  drafts/
    plan.md
```

With `root: 'mirage'`, `/data/drafts/plan.md` is `mirage/drafts/plan.md` in
the origin's OPFS.

## Behavior

* **Origin scope:** another origin, or another browser profile, sees none of
  the files.

### Storage and quotas

The browser sets a quota per origin, typically a fraction of free disk. A
write past it fails with `QuotaExceededError`.

```ts theme={null}
const { quota, usage } = await navigator.storage.estimate()
console.log(`${usage} / ${quota} bytes`)
```

Under storage pressure the browser may evict the data. For a long-lived
workspace, ask for persistent storage early:

```ts theme={null}
await navigator.storage.persist()
```

See [TypeScript Limitations: Browser](https://docs.mirage.strukto.ai/typescript/limitations.md#browser) for
every browser constraint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.