worker-fs-mount

Mount WorkerEntrypoints as virtual filesystems in Cloudflare Workers. This package provides a drop-in replacement for node:fs/promises that intercepts filesystem calls and redirects them to your WorkerEntrypoint implementations via jsrpc.

Features

• Simple setup - Just add an alias to wrangler.toml and your existing node:fs/promises code works
• Multiple mount sources - Works with ctx.exports, service bindings, and Durable Objects
• Full fs coverage - Supports 20+ filesystem operations (read, write, stat, readdir, mkdir, rm, rename, etc.)
• TypeScript-first - Full type definitions with strict types
• Cross-mount safety - Properly handles operations across mount boundaries

Installation

npm install worker-fs-mount

Setup

Add the following alias to your wrangler.toml:

[alias]
"node:fs/promises" = "worker-fs-mount/fs"
"node:fs" = "worker-fs-mount/fs-sync"

This replaces node:fs/promises and node:fs imports with our mount-aware implementations at build time. The node:fs alias is optional - only needed if you use synchronous fs methods.

Quick Start

import { env } from 'cloudflare:workers';
import { mount } from 'worker-fs-mount';
import fs from 'node:fs/promises';

// Mount at module level using importable env
mount('/mnt/storage', env.STORAGE_SERVICE);

export default {
  async fetch(request) {
    // Standard fs operations are automatically intercepted
    await fs.writeFile('/mnt/storage/data.json', JSON.stringify({ hello: 'world' }));
    const content = await fs.readFile('/mnt/storage/data.json', 'utf8');

    // Non-mounted paths work normally
    await fs.readFile('/tmp/local.txt');

    return new Response(content);
  }
};

How It Works

With the wrangler alias configured, every node:fs/promises import is replaced with our implementation. Each filesystem call checks if the path falls under a mounted location:

fs.readFile('/mnt/storage/file.txt')
       ↓
Is '/mnt/storage' mounted? → YES → Call stub.readFile('/file.txt') via jsrpc
       ↓
Is '/tmp/file.txt' mounted? → NO → Use native node:fs/promises

Both import styles work:

import fs from 'node:fs/promises';
import { readFile, writeFile } from 'node:fs/promises';

// Both are intercepted for mounted paths
await fs.readFile('/mnt/storage/file.txt');
await readFile('/mnt/storage/file.txt');

Mount Sources

Service Bindings

// wrangler.toml
// [[services]]
// binding = "STORAGE"
// service = "storage-worker"

mount('/mnt/storage', env.STORAGE);

Same-Worker Entrypoints

export class MyFilesystem extends WorkerEntrypoint {
  async readFile(path) { /* ... */ }
  // ...
}

export default class extends WorkerEntrypoint {
  async fetch() {
    mount('/mnt/local', this.ctx.exports.MyFilesystem);
  }
}

Durable Objects

Access via ctx.exports (recommended) - run wrangler types to generate types:

export class StorageDO extends DurableObject implements WorkerFilesystem {
  // ... implement filesystem methods
}

export default class extends WorkerEntrypoint<Env> {
  async fetch() {
    // ctx.exports provides typed access to your exported Durable Objects
    const id = this.ctx.exports.StorageDO.idFromName('user-123');
    const stub = this.ctx.exports.StorageDO.get(id);
    mount('/mnt/user', stub);
  }
}

Implementing a WorkerFilesystem

Your entrypoint must implement the WorkerFilesystem interface. The interface is stream-first - you implement 6 core methods and higher-level operations like readFile/writeFile are automatically derived.

Here's a minimal in-memory example:

import { WorkerEntrypoint } from 'cloudflare:workers';
import type { WorkerFilesystem, Stat, DirEntry } from 'worker-fs-mount';

export class MemoryFS extends WorkerEntrypoint implements WorkerFilesystem {
  #files = new Map<string, Uint8Array>();
  #dirs = new Set<string>(['/']);

  async stat(path: string): Promise<Stat | null> {
    if (this.#dirs.has(path)) {
      return { type: 'directory', size: 0 };
    }
    const file = this.#files.get(path);
    if (!file) return null;
    return { type: 'file', size: file.length };
  }

  async createReadStream(path: string, options?: { start?: number; end?: number }): Promise<ReadableStream<Uint8Array>> {
    const file = this.#files.get(path);
    if (!file) throw new Error(`ENOENT: ${path}`);
    const start = options?.start ?? 0;
    const end = options?.end !== undefined ? options.end + 1 : file.length;
    const chunk = file.slice(start, end);
    return new ReadableStream({
      start(controller) {
        controller.enqueue(chunk);
        controller.close();
      },
    });
  }

  async createWriteStream(path: string, options?: { start?: number; flags?: 'w' | 'a' | 'r+' }): Promise<WritableStream<Uint8Array>> {
    const self = this;
    let offset = options?.start ?? 0;
    let content = options?.flags === 'a' || options?.flags === 'r+'
      ? (this.#files.get(path) ?? new Uint8Array(0))
      : new Uint8Array(0);
    if (options?.flags === 'a') offset = content.length;

    return new WritableStream({
      write(chunk) {
        const newLength = Math.max(content.length, offset + chunk.length);
        const newContent = new Uint8Array(newLength);
        newContent.set(content, 0);
        newContent.set(chunk, offset);
        content = newContent;
        offset += chunk.length;
        self.#files.set(path, content);
      },
    });
  }

  async readdir(path: string): Promise<DirEntry[]> {
    const prefix = path === '/' ? '/' : path + '/';
    const entries: DirEntry[] = [];
    const seen = new Set<string>();
    for (const [filePath] of this.#files) {
      if (filePath.startsWith(prefix)) {
        const name = filePath.slice(prefix.length).split('/')[0];
        if (name && !seen.has(name)) {
          seen.add(name);
          entries.push({ name, type: 'file' });
        }
      }
    }
    return entries;
  }

  async mkdir(path: string, options?: { recursive?: boolean }): Promise<string | undefined> {
    if (this.#dirs.has(path)) return undefined;
    this.#dirs.add(path);
    return path;
  }

  async rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void> {
    if (!this.#files.delete(path) && !this.#dirs.delete(path)) {
      if (!options?.force) throw new Error(`ENOENT: ${path}`);
    }
  }
}

For production implementations, see the r2-fs, durable-object-fs, and memory-fs packages.

API Reference

mount(path, stub): void

Mount a WorkerFilesystem at the specified path.

| Parameter | Type | Description | |-----------|------|-------------| | path | string | Mount point (must be absolute, start with /) | | stub | WorkerFilesystem | WorkerEntrypoint stub |

unmount(path): boolean

Unmount a filesystem at the specified path.

| Parameter | Type | Description | |-----------|------|-------------| | path | string | Mount point to unmount |

Returns true if a mount was removed, false if nothing was mounted at that path.

withMounts(fn): Promise<T>

Run a function with request-scoped mount isolation. Required for Durable Objects (getting a DO stub is IO). Use when different requests need different mounts (e.g., per-user DOs).

// Durable Objects require request scope - use withMounts for isolation
return withMounts(async () => {
  const userId = getUserId(request);
  const id = ctx.exports.UserStorage.idFromName(userId);
  mount('/user', ctx.exports.UserStorage.get(id));
  // Each request gets its own isolated mount
});

For R2, KV, service bindings, and same-worker entrypoints, prefer mounting at module level using import { env, exports } from 'cloudflare:workers'.

isMounted(path): boolean

Check if a path is under any mount.

isInMountContext(): boolean

Check if code is running inside a withMounts callback.

WorkerFilesystem Interface

The interface is stream-first with minimal required methods. Higher-level operations like readFile, writeFile, truncate, rename, cp, and unlink are automatically derived from these core methods.

Required Methods (6)

| Method | Description | |--------|-------------| | stat(path, options?) | Get file/directory metadata | | createReadStream(path, options?) | Create readable stream for a file | | createWriteStream(path, options?) | Create writable stream for a file | | readdir(path, options?) | List directory contents | | mkdir(path, options?) | Create directory | | rm(path, options?) | Remove file or directory |

Optional Methods (2)

| Method | Description | |--------|-------------| | symlink(linkPath, targetPath) | Create symlink | | readlink(path) | Read symlink target |

Automatically Derived Operations

These node:fs/promises methods are automatically implemented using the core streaming methods:

| Method | Derived From | |--------|--------------| | readFile | createReadStream | | writeFile | createWriteStream | | appendFile | createWriteStream with append flag | | truncate | createReadStream + createWriteStream | | unlink | stat + rm | | copyFile, cp | createReadStream + createWriteStream | | rename | streams + rm | | access | stat |

Supported fs Operations

The following node:fs/promises methods are intercepted:

• readFile, writeFile, appendFile
• stat, lstat
• readdir
• mkdir, rmdir, rm
• unlink
• rename
• copyFile, cp
• access
• truncate
• symlink, readlink
• realpath
• utimes

Synchronous Filesystem (Durable Objects)

When running inside a Durable Object, you can use synchronous filesystem operations by mounting a LocalDOFilesystem. This works because DO's ctx.storage.sql is synchronous within the DO context.

Setup

First, add the node:fs alias to your wrangler.toml:

[alias]
"node:fs/promises" = "worker-fs-mount/fs"
"node:fs" = "worker-fs-mount/fs-sync"

Then use LocalDOFilesystem inside your Durable Object:

import { DurableObject } from 'cloudflare:workers';
import { mount, withMounts } from 'worker-fs-mount';
import { LocalDOFilesystem } from 'durable-object-fs';
import fs from 'node:fs';  // Aliased to worker-fs-mount/fs-sync

export class MyDO extends DurableObject {
  private readonly filesystem = new LocalDOFilesystem(this.ctx.storage);

  fetch(): Response {
    return withMounts(() => {
      mount('/data', this.filesystem);
      const fd = fs.openSync('/data/log.txt', 'a+');
      try {
        fs.writeSync(fd, 'hello\n');
        return Response.json({ size: fs.fstatSync(fd).size });
      } finally {
        fs.closeSync(fd);
      }
    });
  }
}

Unified Mount API

The mount() function accepts both async (WorkerFilesystem) and sync (SyncWorkerFilesystem) filesystems:

// Async filesystem (WorkerEntrypoint via jsrpc)
mount('/mnt/remote', env.STORAGE_SERVICE);

// Sync filesystem (LocalDOFilesystem inside DO)
mount('/data', new LocalDOFilesystem(ctx.storage));

When using the aliased node:fs/promises methods with a sync-only mount, they automatically fall back to the sync methods:

import fs from 'node:fs/promises';

// Even with sync-only LocalDOFilesystem, async methods work
await fs.readFile('/data/file.txt');  // Falls back to readFileSync internally

SyncWorkerFilesystem Interface

To create a sync filesystem, implement SyncWorkerFilesystem:

import type { SyncWorkerFilesystem, SyncFileHandle, SyncOpenOptions, Stat, DirEntry } from 'worker-fs-mount';

class MySyncFs implements SyncWorkerFilesystem {
  statSync(path: string, options?: { followSymlinks?: boolean }): Stat | null { /* ... */ }
  readFileSync(path: string): Uint8Array { /* ... */ }
  writeFileSync(path: string, data: Uint8Array, options?: { flags?: 'w' | 'a' | 'r+' }): void { /* ... */ }
  readdirSync(path: string, options?: { recursive?: boolean }): DirEntry[] { /* ... */ }
  mkdirSync(path: string, options?: { recursive?: boolean }): string | undefined { /* ... */ }
  rmSync(path: string, options?: { recursive?: boolean; force?: boolean }): void { /* ... */ }
  // Optional:
  openFileSync?(path: string, options: SyncOpenOptions): SyncFileHandle;
  renameSync?(oldPath: string, newPath: string): void;
  symlinkSync?(linkPath: string, targetPath: string): void;
  readlinkSync?(path: string): string;
}

Important Notes

• DO Context Only: LocalDOFilesystem only works inside a Durable Object where ctx.storage.sql is available
• Not a WorkerEntrypoint: LocalDOFilesystem operates directly on SQLite storage - it's not accessible via jsrpc
• Use withMounts: isolate mounts and descriptors from other DO instances sharing the same Worker isolate
• Use wrangler alias: Import node:fs with the alias configured for best developer experience
• Storage: pass ctx.storage to enable transactional paged writes and writable descriptors; see durable-object-fs for SQL-only compatibility

Constraints

Sync Operations Require Sync Filesystem

Synchronous node:fs methods only work with filesystems that implement SyncWorkerFilesystem (like LocalDOFilesystem). Using sync methods on async-only mounts throws ENOSYS.

Synchronous file descriptors

Mounts implementing openFileSync support openSync, closeSync, readSync, writeSync, fstatSync, ftruncateSync, fsyncSync, fdatasyncSync, and fchmodSync (when the handle implements chmod). readFileSync, writeFileSync, and appendFileSync also accept these descriptors. Files outside mounts use the native Workers filesystem.

This supports the descriptor I/O used by Emscripten NODERAWFS: numeric open flags, positional reads/writes, truncation, and stat modes containing POSIX file-type bits. String flags, byte views with offsets, append mode, and fstatSync({ bigint: true }) are also supported.

Descriptors belong to the current withMounts() context. Another context cannot use or close them; invalid and closed descriptors throw EBADF. Unmounting or replacing a mount does not redirect an already-open descriptor. Close each descriptor in a finally block within the context that opened it.

A backend's SyncFileHandle owns the opened file identity. Its read and write methods operate on byte offsets; write must honor the open append flag, and truncate must zero-fill extensions. The optional renameSync method allows native rename without the default copy/delete fallback. LocalDOFilesystem(ctx.storage) implements both, including open-file lifetime across rename and unlink.

Async-only RPC mounts and synchronous backends without openFileSync report ENOSYS for mounted descriptor opens. Callback descriptor APIs, promise FileHandles, and Node createReadStream/createWriteStream are not mount-aware. Use the listed sync methods or the mounted node:fs/promises high-level methods; virtual descriptors cannot be passed to native Node APIs.

Same-Mount Operations

rename only works within the same mount. Cross-mount rename throws EXDEV. For cross-mount moves, use copyFile + unlink.

Reserved Paths

Cannot mount over /bundle, /tmp, or /dev.

No Nested Mounts

Cannot mount /mnt/a/b if /mnt/a is already mounted, or vice versa.

Error Handling

Errors follow Node.js conventions with .code property:

| Code | Meaning | |------|---------| | ENOENT | File or directory not found | | EEXIST | File already exists | | ENOTDIR | Expected directory but found file | | EISDIR | Expected file but found directory | | ENOSYS | Operation not supported by filesystem | | EXDEV | Cross-mount operation not supported | | EACCES | Permission denied |

Concurrency

The mounted WorkerFilesystem is responsible for handling concurrent access. For consistent state, use Durable Objects which provide single-threaded execution:

export class StorageDO extends DurableObject implements WorkerFilesystem {
  // All methods automatically serialized by DO runtime
}

License

MIT