-
Notifications
You must be signed in to change notification settings - Fork 10k
Document the node:fs impl #24082
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Document the node:fs impl #24082
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| --- | ||
| title: The Node.js and Web File System APIs in Workers | ||
| description: The node:fs and Web File System APIs are now available in Workers. | ||
| products: | ||
| - workers | ||
| date: 2025-08-15 | ||
| --- | ||
|
|
||
| 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. | ||
|
|
||
| ## Using the `node:fs` module | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| ```js | ||
| import fs from "node:fs"; | ||
|
|
||
| const config = JSON.parse(fs.readFileSync("/bundle/config.json", "utf-8")); | ||
|
|
||
| export default { | ||
| async fetch(request) { | ||
| return new Response(`Config value: ${config.value}`); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| There are a number of initial limitations to the `node:fs` implementation: | ||
|
|
||
| - The glob APIs (e.g. `fs.globSync(...)`) are not implemented. | ||
| - The file watching APIs (e.g. `fs.watch(...)`) are not implemented. | ||
| - The file timestamps (modified time, access time, etc) are only partially supported. For now, these will always return the Unix epoch. | ||
|
|
||
| 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. | ||
|
|
||
| ## The Web File System API | ||
|
|
||
| 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. | ||
|
|
||
| ```js | ||
| const root = navigator.storage.getDirectory(); | ||
|
|
||
| export default { | ||
| async fetch(request) { | ||
| const tmp = await root.getDirectoryHandle("/tmp"); | ||
| const file = await tmp.getFileHandle("data.txt", { create: true }); | ||
| const writable = await file.createWritable(); | ||
| const writer = writable.getWriter(); | ||
| await writer.write("Hello, World!"); | ||
| await writer.close(); | ||
|
|
||
| return new Response("File written successfully!"); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,138 @@ | ||
| --- | ||
| pcx_content_type: configuration | ||
| title: fs | ||
| --- | ||
|
|
||
| import { Render } from "~/components"; | ||
|
|
||
| <Render file="nodejs-compat-howto" product="workers" /> | ||
|
|
||
| You can use [`node:fs`](https://nodejs.org/api/fs.html) to access a virtual file | ||
| system in Workers. | ||
|
|
||
| The `node:fs` module is available in Workers runtimes that support Node.js | ||
| compatibility using the `nodejs_compat` compatibility flag. Any Worker | ||
| running with `nodejs_compat` enabled and with a compatibility date of | ||
| `2025-09-01` or later will have access to `node:fs` by default. It is | ||
| also possible to enable `node:fs` on Workers with an earlier compatibility | ||
| date using a combination of the `nodejs_compat` and `enable_nodejs_fs_module` | ||
| flags. To disable `node:fs` you can set the `disable_nodejs_fs_module` flag. | ||
|
|
||
| ```js | ||
| import { readFileSync, writeFileSync } from "node:fs"; | ||
|
|
||
| const config = readFileSync("/bundle/config.txt", "utf8"); | ||
|
|
||
| writeFileSync("/tmp/abc.txt", "Hello, world!"); | ||
| ``` | ||
|
|
||
| The Workers Virtual File System (VFS) is a memory-based file system that allows | ||
| you to read modules included in your Worker bundle as read-only files, access a | ||
| directory for writing temporary files, or access common | ||
| [character devices](https://linux-kernel-labs.github.io/refs/heads/master/labs/device_drivers.html) like | ||
| `/dev/null`, `/dev/random`, `/dev/full`, and `/dev/zero`. | ||
|
|
||
| The directory structure initially looks like: | ||
|
|
||
| ``` | ||
|
|
||
| /bundle | ||
| └── (one file for each module in your Worker bundle) | ||
| /tmp | ||
| └── (empty, but you can write files, create directories, symlinks, etc) | ||
| /dev | ||
| ├── null | ||
| ├── random | ||
| ├── full | ||
| └── zero | ||
|
|
||
| ``` | ||
|
|
||
| The `/bundle` directory contains the files for all modules included in your | ||
| Worker bundle, which you can read using APIs like `readFileSync` or | ||
| `read(...)`, etc. These are always read-only. Reading from the bundle | ||
| can be useful when you need to read a config file or a template. | ||
|
|
||
| ```js | ||
| import { readFileSync } from "node:fs"; | ||
|
|
||
| // The config.txt file would be included in your Worker bundle. | ||
| // Refer to the Wrangler documentation for details on how to | ||
| // include additional files. | ||
| const config = readFileSync("/bundle/config.txt", "utf8"); | ||
|
|
||
| export default { | ||
| async fetch(request) { | ||
| return new Response(`Config contents: ${config}`); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| The `/tmp` directory is writable, and you can use it to create temporary files | ||
| or directories. You can also create symlinks in this directory. However, the | ||
| contents of `/tmp` are not persistent and are unique to each request. This means | ||
| that files created in `/tmp` within the context of one request will not be | ||
| available in other concurrent or subsequent requests. | ||
|
|
||
| ```js | ||
| import { writeFileSync, readFileSync } from "node:fs"; | ||
|
|
||
| export default { | ||
| fetch(request) { | ||
| // The file `/tmp/hello.txt` will only exist for the duration | ||
| // of this request. | ||
| writeFileSync("/tmp/hello.txt", "Hello, world!"); | ||
| const contents = readFileSync("/tmp/hello.txt", "utf8"); | ||
| return new Response(`File contents: ${contents}`); | ||
| }, | ||
| }; | ||
| ``` | ||
|
|
||
| The `/dev` directory contains common character devices: | ||
|
|
||
| - `/dev/null`: A null device that discards all data written to it and returns | ||
| EOF on read. | ||
| - `/dev/random`: A device that provides random bytes on reads and discards all | ||
| data written to it. Reading from `/dev/random` is only permitted when within | ||
| the context of a request. | ||
| - `/dev/full`: A device that always returns EOF on reads and discards all data | ||
| written to it. | ||
| - `/dev/zero`: A device that provides an infinite stream of zero bytes on reads | ||
| and discards all data written to it. | ||
|
|
||
| All operations on the VFS are synchronous. You can use the synchronous, | ||
jasnell marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| asynchronous callback, or promise-based APIs provided by the `node:fs` module | ||
| but all operations will be performed synchronously. | ||
|
|
||
| Timestamps for files in the VFS are currently always set to the Unix epoch | ||
| (`1970-01-01T00:00:00Z`). This means that operations that rely on timestamps, | ||
| like `fs.stat`, will always return the same timestamp for all files in the VFS. | ||
| This is a temporary limitation that will be addressed in a future release. | ||
|
|
||
| Since all temporary files are held in memory, the total size of all temporary | ||
| files and directories created count towards your Worker’s memory limit. If you | ||
| exceed this limit, the Worker instance will be terminated and restarted. | ||
|
|
||
| The file system implementation has the following limits: | ||
|
|
||
| - The maximum total length of a file path is 4096 characters, including path | ||
| separators. Because paths are handled as file URLs internally, the limit | ||
| accounts for percent-encoding of special characters, decoding characters | ||
| that do not need encoding before the limit is checked. For example, the | ||
| path `/tmp/abcde%66/ghi%zz' is 18 characters long because the `%66`does | ||
| not need to be percent-encoded and is therefore counted as one character, | ||
| while the`%zz` is an invalid percent-encoding that is counted as 3 characters. | ||
| - The maximum number of path segments is 48. For example, the path `/a/b/c` is | ||
| 3 segments. | ||
| - The maximum size of an individual file is 128 MB total. | ||
|
|
||
| The following `node:fs` APIs are not supported in Workers, or are only partially | ||
| supported: | ||
|
|
||
| - `fs.watch` and `fs.watchFile` operations for watching for file changes. | ||
| - The `fs.globSync()` and other glob APIs have not yet been implemented. | ||
| - The `force` option in the `fs.rm` API has not yet bee implemented. | ||
| - Timestamps for files are always set to the Unix epoch (`1970-01-01T00:00:00Z`). | ||
| - File permissions and ownership are not supported. | ||
|
|
||
| The full `node:fs` API is documented in the [Node.js documentation for `node:fs`](https://nodejs.org/api/fs.html). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.