Skip to content

Commit 1ef8393

Browse files
jasnellvicb
jasnell
authored and
vicb
committed
Document the node:fs impl
1 parent 5dd9bed commit 1ef8393

File tree

5 files changed

+228
-1
lines changed

5 files changed

+228
-1
lines changed

‎src/content/changelog/workers/2025-08-15-nodejs-fs.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: The Node.js and Web File System APIs in Workers
3+
description: The node:fs and Web File System APIs are now available in Workers.
4+
products:
5+
- workers
6+
date: 2025-08-15T01:00:00Z
7+
---
8+
9+
Implementations of the [`node:fs` module](https://nodejs.org/docs/latest/api/fs.html) and the [Web File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API) are now available in Workers.
10+
11+
## Using the `node:fs` module
12+
13+
The `node:fs` module provides access to a virtual file system in Workers. You can use it to read and write files, create directories, and perform other file system operations.
14+
15+
The virtual file system is ephemeral with each individual request havig its own isolated temporary file space. Files written to the file system will not persist across requests and will not be shared across requests or across different Workers.
16+
17+
Workers running with the `nodejs_compat` compatibility flag will have access to the `node:fs` module by default when the compatibility date is set to `2025-09-01` or later. Support for the API can also be enabled using the `enable_nodejs_fs_module` compatibility flag together with the `nodejs_compat` flag. The `node:fs` module can be disabled using the `disable_nodejs_fs_module` compatibility flag.
18+
19+
```js
20+
import fs from 'node:fs';
21+
22+
const config = JSON.parse(fs.readFileSync('/bundle/config.json', 'utf-8'));
23+
24+
export default {
25+
async fetch(request) {
26+
return new Response(`Config value: ${config.value}`);
27+
}
28+
}
29+
```
30+
31+
There are a number of initial limitations to the `node:fs` implementation:
32+
33+
* The glob APIs (e.g. `fs.globSync(...)`) are not implemented.
34+
* The file watching APIs (e.g. `fs.watch(...)`) are not implemented.
35+
* The file timestamps (modified time, access time, etc) are only partially supported. For now, these will always return the Unix epoch.
36+
37+
Refer to the [Node.js documentation](https://nodejs.org/docs/latest/api/fs.html) for more information on the `node:fs` module and its APIs.
38+
39+
## The Web File System API
40+
41+
The Web File System API provides access to the same virtual file system as the `node:fs` module, but with a different API surface. The Web File System API is only available in Workers running with the `enable_web_file_system` compatibility flag. The `nodejs_compat` compatibility flag is not required to use the Web File System API.
42+
43+
```js
44+
const root = navigator.storage.getDirectory();
45+
46+
export default {
47+
async fetch(request) {
48+
const tmp = await root.getDirectoryHandle('/tmp');
49+
const file = await tmp.getFileHandle('data.txt', { create: true });
50+
const writable = await file.createWritable();
51+
const writer = writable.getWriter();
52+
await writer.write('Hello, World!');
53+
await writer.close();
54+
55+
return new Response('File written successfully!');
56+
}
57+
}
58+
```
59+
60+
As there are still some parts of the Web File System API tht are not fully standardized, there may be some differences between the Workers implementation and the implementations in browsers.

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

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
pcx_content_type: configuration
3+
title: fs
4+
---
5+
6+
import { Render, TypeScriptExample } from "~/components";
7+
8+
<Render file="nodejs-compat-howto" />
9+
10+
You can use [`node:fs`](https://nodejs.org/api/fs.html) to access a virtual file
11+
system in Workers.
12+
13+
The `node:fs` module is available in Workers runtimes that support Node.js
14+
compatibility using the `nodejs_compat` compatibility flag. Any Worker
15+
running with `nodejs_compat` enabled and with a compatibility date of
16+
`2025-09-01` or later will have access to `node:fs` by default. It is
17+
also possible to enable `node:fs` on Workers with an earlier compatibility
18+
date using a comgination of the `nodejs_compat` and `enable_nodejs_fs_module`
19+
flags. To disable `node:fs` you can set the `disable_nodejs_fs_module` flag.
20+
21+
<TypeScriptExample filename="index.ts">
22+
```ts
23+
import { readFileSync, writeFileSync } from 'node:fs';
24+
25+
const config = readFileSync('/bundle/config.txt', 'utf8');
26+
27+
writeFileSync('/tmp/abc.txt', 'Hello, world!');
28+
```
29+
</TypeScriptExample>
30+
31+
The Workers Virtual File System (VFS) is a memory-based file system that allows
32+
you to read modules included in your Worker bundle as read-only files, access a
33+
directory for writing temporary files, or access common
34+
[character devices](https://linux-kernel-labs.github.io/refs/heads/master/labs/device_drivers.html) like
35+
`/dev/null`, `/dev/random`, `/dev/full`, and `/dev/zero`.
36+
37+
The directory structure initially looks like:
38+
39+
```
40+
/bundle
41+
└── (one file for each module in your Worker bundle)
42+
/tmp
43+
└── (empty, but you can write files, create directories, symlinks, etc)
44+
/dev
45+
├── null
46+
├── random
47+
├── full
48+
└── zero
49+
```
50+
51+
The `/bundle` directory contains the files for all modules included in your
52+
Worker bundle, which you can read using APIs like `readFileSync` or
53+
`read(...)`, etc. These are always read-only. Reading from the bundle
54+
can be useful when you need to read a config file or a template.
55+
56+
```javascript
57+
import { readFileSync } from 'node:fs';
58+
59+
// The config.txt file would be included in your Worker bundle.
60+
// Refer to the Wrangler documentation for details on how to
61+
// include additional files.
62+
const config = readFileSync('/bundle/config.txt', 'utf8');
63+
64+
export default {
65+
async fetch(request) {
66+
return new Response(`Config contents: ${config}`);
67+
},
68+
}
69+
```
70+
71+
The `/tmp` directory is writable, and you can use it to create temporary files
72+
or directories. You can also create symlinks in this directory. However, the
73+
contents of `/tmp` are not persistent and are unique to each request. This means
74+
that files created in `/tmp` within the context of one request will not be
75+
available in other concurrent or subsequent requests.
76+
77+
```javascript
78+
import { writeFileSync, readFileSync } from 'node:fs';
79+
80+
export default {
81+
fetch(request) {
82+
// The file `/tmp/hello.txt` will only exist for the duration
83+
// of this request.
84+
writeFileSync('/tmp/hello.txt', 'Hello, world!');
85+
const contents = readFileSync('/tmp/hello.txt', 'utf8');
86+
return new Response(`File contents: ${contents}`);
87+
}
88+
}
89+
```
90+
91+
The `/dev` directory contains common character devices:
92+
93+
* `/dev/null`: A null device that discards all data written to it and returns
94+
EOF on read.
95+
* `/dev/random`: A device that provides random bytes on reads and discards all
96+
data written to it. Reading from `/dev/random` is only permitted when within
97+
the context of a request.
98+
* `/dev/full`: A device that always returns EOF on reads and discards all data
99+
written to it.
100+
* `/dev/zero`: A device that provides an infinite stream of zero bytes on reads
101+
and discards all data written to it.
102+
103+
All operations on the VFS are synchronous. You can use the synchronous,
104+
asynchronous callback, or promise-based APIs provided by the `node:fs` module
105+
but all operations will be performed synchronously.
106+
107+
Timestamps for files in the VFS are currently always set to the Unix epoch
108+
(`1970-01-01T00:00:00Z`). This means that operations that rely on timestamps,
109+
like `fs.stat`, will always return the same timestamp for all files in the VFS.
110+
This is a temporary limitation that will be addressed in a future release.
111+
112+
Since all temporary files are held in memory, the total size of all temporary
113+
files and directories created count towards your Worker’s memory limit. If you
114+
exceed this limit, the Worker instance will be terminated and restarted.
115+
116+
The file system implementation has the following limits:
117+
118+
* The maximum total length of a file path is 4096 characters, including path
119+
separators. Because paths are handled as file URLs internally, the limit
120+
accounts for percent-encoding of special characters, decoding characters
121+
that do not need encoding before the limit is checked. For example, the
122+
path `/tmp/abcde%66/ghi%zz' is 18 characters long because the `%66` does
123+
not need to be percent-encoded and is therefore counted as one character,
124+
while the `%zz` is an invalid percent-encoding that is counted as 3 characters.
125+
* The maximum number of path segments is 48. For example, the path `/a/b/c` is
126+
3 segments.
127+
* The maximum size of an individual file is 128 MB total.
128+
129+
The following `node:fs` APIs are not supported in Workers, or are only partially
130+
supported:
131+
132+
* `fs.watch` and `fs.watchFile` operations for watching for file changes.
133+
* The `fs.globSync()` and other glob APIs have not yet been implemented.
134+
* The `force` option in the `fs.rm` API has not yet bee implemented.
135+
* Timestamps for files are always set to the Unix epoch (`1970-01-01T00:00:00Z`).
136+
* File permissions and ownership are not supported.
137+
138+
:::
139+
140+
The full `node:fs` API is documented in the [Node.js documentation for `node:fs`](https://nodejs.org/api/fs.html).

‎src/content/docs/workers/runtime-apis/nodejs/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ The runtime APIs from Node.js listed below as "🟢 supported" are currently nat
4545
| [DNS](/workers/runtime-apis/nodejs/dns/) | 🟢 supported |
4646
| Errors | 🟢 supported |
4747
| Events | 🟢 supported |
48-
| File system | ⚪ coming soon |
48+
| File system | 🟢 supported |
4949
| Globals | 🟢 supported |
5050
| [HTTP](/workers/runtime-apis/nodejs/http/) | 🟢 supported |
5151
| HTTP/2 | ⚪ not yet supported |

‎src/content/docs/workers/runtime-apis/web-standards.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,27 @@ with `navigator.sendBeacon(...)`:
205205
```js
206206
navigator.sendBeacon('https://example.com', 'hello world');
207207
```
208+
209+
## The Web File System Access API
210+
211+
When the `enable_web_file_system` compatibility flag is set, Workers supports the [Web File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API), which allows you to read and write files and directories to a virtual file system within the Worker environment. This API provides access to the same in-memory virtual file system as the [`node:fs` module](/workers/runtime-apis/nodejs/fs/) but does not require Node.js compatibility to be enabled.
212+
213+
```js
214+
const root = await navigator.storage.getDirctory();
215+
216+
export default {
217+
async fetch(request) {
218+
const fileHandle = await root.getFileHandle('hello.txt', { create: true });
219+
const writable = await fileHandle.createWritable();
220+
await writable.write('Hello, world!');
221+
await writable.close();
222+
223+
const file = await fileHandle.getFile();
224+
const contents = await file.text();
225+
226+
return new Response(contents, { status: 200 });
227+
}
228+
}
229+
```
230+
231+
Please refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API) for more information on using this API, and to the [`node:fs` documentation](/workers/runtime-apis/nodejs/fs/) for details on the virtual file system structure and limitations.

‎src/content/release-notes/workers.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ entries:
66
- publish_date: "2025-09-18"
77
description: |-
88
- Updated v8 to version 14.1.
9+
- publish_date: "2025-09-11"
10+
description: |-
11+
- The node:fs and Web File System APIs are now available within Workers.
912
- publish_date: "2025-08-21"
1013
description: |-
1114
- Updated v8 to version 14.0.

0 commit comments

Comments
 (0)