Which package should I use?
Start with @effect-vfs/memory unless you need to control the underlying virtual volume directly. The four public
packages can be used together.
Package overview
| Package | Choose it when you need | Main abstraction |
|---|---|---|
@effect-vfs/memory | Existing Effect code should use an isolated in-memory filesystem | FileSystem.FileSystem |
@effect-vfs/core | You need explicit volumes, callers, byte paths, permissions, fixtures, quotas, watches, snapshots, or overlays | Volume and Caller |
@effect-vfs/persistence | You need named SQLite checkpoints or a live volume backed by SQLite or R2 | CheckpointStore or a LiveImageStore |
@effect-vfs/nfs | Native NFSv4.1 clients need read-only access or experimental writes to a qualified live volume | NfsServer |
Start with memory
@effect-vfs/memory implements Effect's standard FileSystem service. Application code continues to request
FileSystem.FileSystem; only the layer supplied at runtime changes.
Use it for tests, build previews, code generators, browser tools, and other programs that need disposable filesystem state without host filesystem I/O.
program.pipe(Effect.provide(MemoryFileSystem.layer), Effect.provide(BunCrypto.layer))Read Getting started for a complete program or open the
MemoryFileSystem API reference.
Add core for explicit control
@effect-vfs/core owns filesystem state and its bounded POSIX behavior. Use it directly when you need capabilities
that do not fit Effect's string-based FileSystem interface, including:
- byte-preserving paths;
- explicit caller identities, permissions, working directories, and creation masks;
- shared volumes and change streams;
- fixtures, quotas, snapshots, overlays, or snapshot deltas; and
- scoped file and directory handles.
You can create a core volume and expose the same state through MemoryFileSystem.bind. This lets ordinary Effect
filesystem code and lower-level core callers work with one shared namespace.
Open the VirtualFileSystem API reference for the complete core surface.
Read Volumes, callers, and handles for the ownership, authority, and scope model.
Add persistence
@effect-vfs/persistence stores immutable snapshots under create-only names in SQLite. Applications still own:
- capturing the snapshot;
- providing and migrating the database;
- choosing decode and resource limits; and
- restoring the loaded snapshot into a fresh volume.
Checkpoints do not save mutations automatically or provide listing, replacement, deletion, or history.
For live writes, SqliteLiveImageStore backs LiveVolume.open with a dedicated SQLite database. Its current
durability tier is memory-only; process-restart tests do not prove OS-crash or power-loss durability.
Open the CheckpointStore API reference for its public service and error types.
Follow Save and restore SQLite checkpoints for a complete file-backed example.
Read Back a live volume with SQLite for live-store setup and limits.
Export a local read-only NFS volume
@effect-vfs/nfs serves one live core volume to native NFSv4.1 clients. The local read-only profile is a preview.
Mutating NFS operations return NFS4ERR_ROFS; applications can still change the volume through the VFS API.
Read Export a volume over local NFS for the server setup and mount boundary.
For experimental writes, the volume must report survives-power-loss, and the application must supply a peer and
identity policy. The writable R2 example shows the bounded
single-gateway profile and its limits.