Add worker-fs-mount docs to node:fs page

[ask-bonk]

Here is a summary of the changes made to src/content/docs/workers/runtime-apis/nodejs/fs.mdx:

What changed

New content: "Mount persistent storage with worker-fs-mount" section

The existing node:fs docs only covered the built-in ephemeral virtual file system (/bundle, /tmp, /dev). The worker-fs-mount repository demonstrates a significant pattern — mounting Cloudflare storage services as virtual filesystem paths accessible through standard node:fs APIs — that was entirely undocumented. The new section covers:

1. How it works — Explains the Wrangler module aliasing mechanism that intercepts node:fs imports and routes operations to storage backends based on path prefixes.

2. Installation and Wrangler configuration — Step-by-step setup including the critical [alias] configuration and the node: prefix requirement to avoid alias loops.

3. Mount an R2 bucket — Complete example showing module-scope mounting of R2 with WranglerConfig and a working code sample.

4. Mount a Durable Object — Example using withMounts() for request-scoped mounting with AsyncLocalStorage isolation, important because DO stubs require I/O to obtain.

5. Synchronous access inside Durable Objects — Pattern for using LocalDOFilesystem with readFileSync/writeFileSync directly inside a DO, accessing SQLite storage synchronously.

6. Supported operations table — Full reference of which node:fs methods work on mounted paths (both async and sync variants).

7. Mount rules — Constraints on mount paths (absolute paths, reserved paths, no nesting).

8. Storage backends comparison — Collapsible table comparing R2, Durable Object (remote and local), and in-memory backends.

Pre-existing content improvements

• Added H2/H3 headings to structure the VFS section (previously a flat wall of text)
• Fixed broken inline code formatting on the path example (mismatched backtick/quote, missing spaces, lost list indentation)
• Fixed gerund headings ("Reading from" -> "Read from", "Writing temporary" -> "Write temporary")
• Fixed title-case heading ("Virtual File System" -> "Virtual file system")
• Removed forward-looking language ("will be addressed in a future release" -> "known limitation")
• Added compatibility_date = "$today" to all WranglerConfig blocks

Closes #28431

github run

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/workers/	@cloudflare/workers-docs, @GregBrimble, @irvinebroque, @mikenomitch, @korinne, @WalshyDev, @cloudflare/deploy-config, @cloudflare/pcx-technical-writing, @cloudflare/wrangler, @mattietk, @cloudflare/dev-plat-leads

[irvinebroque]

/bonk please revise these docs with my feedback, that the docs need to explain the pattern that worker-fs-mount implements, but shouldn't link directly or tell people to depend on it. The purpose of these docs should be to help a human or agent understand how they could implement this on their own. Since the docs here on fs are long, it may make sense to break this out into a tutorial or example, separately in the docs, so that there is space to go into enough detail.

[irvinebroque]

This should not link direct to that project or treat it like it is a package to depend on

[irvinebroque]

We shouldnt reference Unix mount points, people reading dont know what that is

[irvinebroque]

/bonk please revise these docs with my feedback, that the docs need to explain the pattern that worker-fs-mount implements, but shouldn't link directly or tell people to depend on it. The purpose of these docs should be to help a human or agent understand how they could implement this on their own. Since the docs here on fs are long, it may make sense to break this out into a tutorial or example, separately in the docs, so that there is space to go into enough detail.

[ask-bonk]

All done. Here is a summary of the changes:

Changes made

1. Revised src/content/docs/workers/runtime-apis/nodejs/fs.mdx

Replaced the entire "Mount persistent storage with worker-fs-mount" section (221 lines removed) with a concise 9-line section called "Use persistent storage with node:fs" that:

• Explains the pattern conceptually (custom node:fs shim + Wrangler module aliasing + path-prefix routing to storage backends)
• Does not link to or mention worker-fs-mount as a package to install
• Does not reference "Unix mount points"
• Links to the new tutorial for step-by-step implementation details
• Removed the unused Details and WranglerConfig component imports

2. Created src/content/docs/workers/tutorials/mount-persistent-storage-as-a-file-system.mdx

A 581-line Advanced tutorial that teaches the pattern from scratch, with 7 numbered steps:

1. Understand the approach — Explains Wrangler module aliasing and the "fs" vs "node:fs" import trick to avoid alias loops
2. Define the storage backend interface — 6-method stream-based StorageBackend interface with derived operations explained
3. Build a mount registry — mount() and findMount() with reserved-path validation
4. Write the fs shim — Complete shim module with readFile, writeFile, stat, readdir, mkdir, rm, and stream helpers
5. Implement an R2 storage backend — Full R2StorageBackend class with R2-specific concerns (flat keys, directory markers, paginated listing)
6. Configure Wrangler and wire everything together — Complete configuration and entry point
7. Handle per-request backends with AsyncLocalStorage — Optional step for Durable Object backends requiring request-scoped isolation

Validation

• npm run check — 0 errors
• npm run lint — clean
• npm run format:core:check — all files pass

github run

[irvinebroque]

@danlapid WDYT about having a guide like this that unpacks how you can implement https://github.com/danlapid/worker-fs-mount