Post Syndicated from James M Snell original https://blog.cloudflare.com/nodejs-workers-2025/
We’ve been busy.
Compatibility with the broad JavaScript developer ecosystem has always been a key strategic investment for us. We believe in open standards and an open web. We want you to see Workers as a powerful extension of your development platform with the ability to just drop code in that Just Works. To deliver on this goal, the Cloudflare Workers team has spent the past year significantly expanding compatibility with the Node.js ecosystem, enabling hundreds (if not thousands) of popular npm modules to now work seamlessly, including the ever popular express framework.
We have implemented a substantial subset of the Node.js standard library, focusing on the most commonly used, and asked for, APIs. These include:
| Module | API documentation |
|---|---|
| node:console | https://nodejs.org/docs/latest/api/console.html |
| node:crypto | https://nodejs.org/docs/latest/api/crypto.html |
| node:dns | https://nodejs.org/docs/latest/api/dns.html |
| node:fs | https://nodejs.org/docs/latest/api/fs.html |
| node:http | https://nodejs.org/docs/latest/api/http.html |
| node:https | https://nodejs.org/docs/latest/api/https.html |
| node:net | https://nodejs.org/docs/latest/api/net.html |
| node:process | https://nodejs.org/docs/latest/api/process.html |
| node:timers | https://nodejs.org/docs/latest/api/timers.html |
| node:tls | https://nodejs.org/docs/latest/api/tls.html |
| node:zlib | https://nodejs.org/docs/latest/api/zlib.html |
Each of these has been carefully implemented to approximate Node.js’ behavior as closely as possible where feasible. Where matching Node.js‘ behavior is not possible, our implementations will throw a clear error when called, rather than silently failing or not being present at all. This ensures that packages that check for the presence of these APIs will not break, even if the functionality is not available.
In some cases, we had to implement entirely new capabilities within the runtime in order to provide the necessary functionality. For node:fs, we added a new virtual file system within the Workers environment. In other cases, such as with node:net, node:tls, and node:http, we wrapped the new Node.js APIs around existing Workers capabilities such as the Sockets API and fetch.
Most importantly, all of these implementations are done natively in the Workers runtime, using a combination of TypeScript and C++. Whereas our earlier Node.js compatibility efforts relied heavily on polyfills and shims injected at deployment time by developer tooling such as Wrangler, we are moving towards a model where future Workers will have these APIs available natively, without need for any additional dependencies. This not only improves performance and reduces memory usage, but also ensures that the behavior is as close to Node.js as possible.
Node.js has a rich set of networking APIs that allow applications to create servers, make HTTP requests, work with raw TCP and UDP sockets, send DNS queries, and more. Workers do not have direct access to raw kernel-level sockets though, so how can we support these Node.js APIs so packages still work as intended? We decided to build on top of the existing managed Sockets and fetch APIs. These implementations allow many popular Node.js packages that rely on networking APIs to work seamlessly in the Workers environment.
Let’s start with the HTTP APIs.
From the moment we announced that we would be pursuing Node.js compatibility within Workers, users have been asking specifically for an implementation of the node:http module. There are countless modules in the ecosystem that depend directly on APIs like http.get(...) and http.createServer(...).
The node:http and node:https modules provide APIs for creating HTTP clients and servers. We have implemented both, allowing you to create HTTP clients using http.request() and servers using http.createServer(). The HTTP client implementation is built on top of the Fetch API, while the HTTP server implementation is built on top of the Workers runtime’s existing request handling capabilities.
The client side is fairly straightforward:
import http from 'node:http';
export default {
async fetch(request) {
return new Promise((resolve, reject) => {
const req = http.request('http://example.com', (res) => {
let data = '';
res.setEncoding('utf8');
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
resolve(new Response(data));
});
});
req.on('error', (err) => {
reject(err);
});
req.end();
});
}
}
The server side is just as simple but likely even more exciting. We’ve often been asked about the possibility of supporting Express, or Koa, or Fastify within Workers, but it was difficult to do because these were so dependent on the Node.js APIs. With the new additions it is now possible to use both Express and Koa within Workers, and we’re hoping to be able to add Fastify support later.
import { createServer } from "node:http";
import { httpServerHandler } from "cloudflare:node";
const server = createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello from Node.js HTTP server!");
});
export default httpServerHandler(server);
The httpServerHandler() function from the cloudflare:node module integrates the HTTP server with the Workers fetch event, allowing it to handle incoming requests.
The node:dns module provides an API for performing DNS queries.
At Cloudflare, we happen to have a DNS-over-HTTPS (DoH) service and our own DNS service called 1.1.1.1. We took advantage of this when exposing node:dns in Workers. When you use this module to perform a query, it will just make a subrequest to 1.1.1.1 to resolve the query. This way the user doesn’t have to think about DNS servers, and the query will just work.
The node:net module provides an API for creating TCP sockets, while the node:tls module provides an API for creating secure TLS sockets. As we mentioned before, both are built on top of the existing Workers Sockets API. Note that not all features of the node:net and node:tls modules are available in Workers. For instance, it is not yet possible to create a TCP server using net.createServer() yet (but maybe soon!), but we have implemented enough of the APIs to allow many popular packages that rely on these modules to work in Workers.
import net from 'node:net';
import tls from 'node:tls';
export default {
async fetch(request) {
const { promise, resolve } = Promise.withResolvers();
const socket = net.connect({ host: 'example.com', port: 80 },
() => {
let buf = '';
socket.setEncoding('utf8')
socket.on('data', (chunk) => buf += chunk);
socket.on('end', () => resolve(new Response('ok'));
socket.end();
});
return promise;
}
}
What does supporting filesystem APIs mean in a serverless environment? When you deploy a Worker, it runs in Region:Earth and we don’t want you needing to think about individual servers with individual file systems. There are, however, countless existing applications and modules in the ecosystem that leverage the file system to store configuration data, read and write temporary data, and more.
Workers do not have access to a traditional file system like a Node.js process does, and for good reason! A Worker does not run on a single machine; a single request to one worker can run on any one of thousands of servers anywhere in Cloudflare’s global network. Coordinating and synchronizing access to shared physical resources such as a traditional file system harbor major technical challenges and risks of deadlocks and more; challenges that are inherent in any massively distributed system. Fortunately, Workers provide powerful tools like Durable Objects that provide a solution for coordinating access to shared, durable state at scale. To address the need for a file system in Workers, we built on what already makes Workers great.
We implemented a virtual file system that allows you to use the node:fs APIs to read and write temporary, in-memory files. This virtual file system is specific to each Worker. When using a stateless worker, files created in one request are not accessible in any other request. However, when using a Durable Object, this temporary file space can be shared across multiple requests from multiple users. This file system is ephemeral (for now), meaning that files are not persisted across Worker restarts or deployments, so it does not replace the use of the Durable Object Storage mechanism, but it provides a powerful new tool that greatly expands the capabilities of your Durable Objects.
The node:fs module provides a rich set of APIs for working with files and directories:
import fs from 'node:fs';
export default {
async fetch(request) {
// Write a temporary file
await fs.promises.writeFile('/tmp/hello.txt', 'Hello, world!');
// Read the file
const data = await fs.promises.readFile('/tmp/hello.txt', 'utf-8');
return new Response(`File contents: ${data}`);
}
}
The virtual file system supports a wide range of file operations, including reading and writing files, creating and removing directories, and working with file descriptors. It also supports standard input/output/error streams via process.stdin, process.stdout, and process.stderr, symbolic links, streams, and more.
While the current implementation of the virtual file system is in-memory only, we are exploring options for adding persistent storage in the future that would link to existing Cloudflare storage solutions like R2 or Durable Objects. But you don’t have to wait on us! When combined with powerful tools like Durable Objects and JavaScript RPC, it’s certainly possible to create your own general purpose, durable file system abstraction backed by sqlite storage.
The node:crypto module provides a comprehensive set of cryptographic functionality, including hashing, encryption, decryption, and more. We have implemented a full version of the node:crypto module, allowing you to use familiar cryptographic APIs in your Workers applications. There will be some difference in behavior compared to Node.js due to the fact that Workers uses BoringSSL under the hood, while Node.js uses OpenSSL. However, we have strived to make the APIs as compatible as possible, and many popular packages that rely on node:crypto now work seamlessly in Workers.
To accomplish this, we didn’t just copy the implementation of these cryptographic operations from Node.js. Rather, we worked within the Node.js project to extract the core crypto functionality out into a separate dependency project called ncrypto that is used – not only by Workers but Bun as well – to implement Node.js compatible functionality by simply running the exact same code that Node.js is running.
import crypto from 'node:crypto';
export default {
async fetch(request) {
const hash = crypto.createHash('sha256');
hash.update('Hello, world!');
const digest = hash.digest('hex');
return new Response(`SHA-256 hash: ${digest}`);
}
}
All major capabilities of the node:crypto module are supported, including:
-
Hashing (e.g., SHA-256, SHA-512)
-
HMAC
-
Symmetric encryption/decryption
-
Asymmetric encryption/decryption
-
Digital signatures
-
Key generation and management
-
Random byte generation
-
Key derivation functions (e.g., PBKDF2, scrypt)
-
Cipher and Decipher streams
-
Sign and Verify streams
-
KeyObject class for managing keys
-
Certificate handling (e.g., X.509 certificates)
-
Support for various encoding formats (e.g., PEM, DER, base64)
-
and more…
In Node.js, the node:process module provides a global object that gives information about, and control over, the current Node.js process. It includes properties and methods for accessing environment variables, command-line arguments, the current working directory, and more. It is one of the most fundamental modules in Node.js, and many packages rely on it for basic functionality and simply assume its presence. There are, however, some aspects of the node:process module that do not make sense in the Workers environment, such as process IDs and user/group IDs which are tied to the operating system and process model of a traditional server environment and have no equivalent in the Workers environment.
When nodejs_compat is enabled, the process global will be available in your Worker scripts or you can import it directly via import process from 'node:process'. Note that the process global is only available when the nodejs_compat flag is enabled. If you try to access process without the flag, it will be undefined and the import will throw an error.
Let’s take a look at the process APIs that do make sense in Workers, and that have been fully implemented, starting with process.env.
Workers have had support for environment variables for a while now, but previously they were only accessible via the env argument passed to the Worker function. Accessing the environment at the top-level of a Worker was not possible:
export default {
async fetch(request, env) {
const config = env.MY_ENVIRONMENT_VARIABLE;
// ...
}
}
With the new process.env implementation, you can now access environment variables in a more familiar way, just like in Node.js, and at any scope, including the top-level of your Worker:
import process from 'node:process';
const config = process.env.MY_ENVIRONMENT_VARIABLE;
export default {
async fetch(request, env) {
// You can still access env here if you need to
const configFromEnv = env.MY_ENVIRONMENT_VARIABLE;
// ...
}
}
Environment variables are set in the same way as before, via the wrangler.toml or wrangler.jsonc configuration file, or via the Cloudflare dashboard or API. They may be set as simple key-value pairs or as JSON objects:
{
"name": "my-worker-dev",
"main": "src/index.js",
"compatibility_date": "2025-09-15",
"compatibility_flags": [
"nodejs_compat"
],
"vars": {
"API_HOST": "example.com",
"API_ACCOUNT_ID": "example_user",
"SERVICE_X_DATA": {
"URL": "service-x-api.dev.example",
"MY_ID": 123
}
}
}
When accessed via process.env, all environment variable values are strings, just like in Node.js.
Because process.env is accessible at the global scope, it is important to note that environment variables are accessible from anywhere in your Worker script, including third-party libraries that you may be using. This is consistent with Node.js behavior, but it is something to be aware of from a security and configuration management perspective. The Cloudflare Secrets Store can provide enhanced handling around secrets within Workers as an alternative to using environment variables.
When not using the nodejs_compat flag, we decided to go a step further and make it possible to import both the environment, and the waitUntil mechanism, as a module, rather than forcing users to always access it via the env and ctx arguments passed to the Worker function. This can make it easier to access the environment in a more modular way, and can help to avoid passing the env argument through multiple layers of function calls. This is not a Node.js-compatibility feature, but we believe it is a useful addition to the Workers environment:
import { env, waitUntil } from 'cloudflare:workers';
const config = env.MY_ENVIRONMENT_VARIABLE;
export default {
async fetch(request) {
// You can still access env here if you need to
const configFromEnv = env.MY_ENVIRONMENT_VARIABLE;
// ...
}
}
function doSomething() {
// Bindings and waitUntil can now be accessed without
// passing the env and ctx through every function call.
waitUntil(env.RPC.doSomethingRemote());
}
One important note about process.env: changes to environment variables via process.env will not be reflected in the env argument passed to the Worker function, and vice versa. The process.env is populated at the start of the Worker execution and is not updated dynamically. This is consistent with Node.js behavior, where changes to process.env do not affect the actual environment variables of the running process. We did this to minimize the risk that a third-party library, originally meant to run in Node.js, could inadvertently modify the environment assumed by the rest of the Worker code.
Workers do not have a traditional standard input/output/error streams like a Node.js process does. However, we have implemented process.stdin, process.stdout, and process.stderr as stream-like objects that can be used similarly. These streams are not connected to any actual process stdin and stdout, but they can be used to capture output that is written to the logs captured by the Worker in the same way as console.log and friends, just like them, they will show up in Workers Logs.
The process.stdout and process.stderr are Node.js writable streams:
import process from 'node:process';
export default {
async fetch(request) {
process.stdout.write('This will appear in the Worker logs\n');
process.stderr.write('This will also appear in the Worker logs\n');
return new Response('Hello, world!');
}
}
Support for stdin, stdout, and stderr is also integrated with the virtual file system, allowing you to write to the standard file descriptors 0, 1, and 2 (representing stdin, stdout, and stderr respectively) using the node:fs APIs:
import fs from 'node:fs';
import process from 'node:process';
export default {
async fetch(request) {
// Write to stdout
fs.writeSync(process.stdout.fd, 'Hello, stdout!\n');
// Write to stderr
fs.writeSync(process.stderr.fd, 'Hello, stderr!\n');
return new Response('Check the logs for stdout and stderr output!');
}
}
We cannot cover every node:process API in detail here, but here are some of the other notable APIs that we have implemented:
-
process.nextTick(fn): Schedules a callback to be invoked after the current execution context completes. Our implementation uses the same microtask queue as promises so that it behaves exactly the same asqueueMicrotask(fn). -
process.cwd()andprocess.chdir(): Get and change the current virtual working directory. The current working directory is initialized to /bundlewhen the Worker starts, and every request has its own isolated view of the current working directory. Changing the working directory in one request does not affect the working directory in other requests. -
process.exit(): Immediately terminates the current Worker request execution. This is unlike Node.js whereprocess.exit()terminates the entire process. In Workers, callingprocess.exit()will stop execution of the current request and return an error response to the client.
The node:zlib module provides APIs for compressing and decompressing data using various algorithms such as gzip, deflate, and brotli. We have implemented the node:zlib module, allowing you to use familiar compression APIs in your Workers applications. This enables a wide range of use cases, including data compression for network transmission, response optimization, and archive handling.
import zlib from 'node:zlib';
export default {
async fetch(request) {
const input = 'Hello, world! Hello, world! Hello, world!';
const compressed = zlib.gzipSync(input);
const decompressed = zlib.gunzipSync(compressed).toString('utf-8');
return new Response(`Decompressed data: ${decompressed}`);
}
}
While Workers has had built-in support for gzip and deflate compression via the Web Platform Standard Compression API, the node:zlib module support brings additional support for the Brotli compression algorithm, as well as a more familiar API for Node.js developers.
Node.js provides a set of timing and scheduling APIs via the node:timers module. We have implemented these in the runtime as well.
import timers from 'node:timers';
export default {
async fetch(request) {
timers.setInterval(() => {
console.log('This will log every half-second');
}, 500);
timers.setImmediate(() => {
console.log('This will log immediately after the current event loop');
});
return new Promise((resolve) => {
timers.setTimeout(() => {
resolve(new Response('Hello after 1 second!'));
}, 1000);
});
}
}
The Node.js implementations of the timers APIs are very similar to the standard Web Platform with one key difference: the Node.js timers APIs return Timeout objects that can be used to manage the timers after they have been created. We have implemented the Timeout class in Workers to provide this functionality, allowing you to clear or re-fire timers as needed.
The node:console module provides a set of console logging APIs that are similar to the standard console global, but with some additional features. We have implemented the node:console module as a thin wrapper around the existing globalThis.console that is already available in Workers.
To enable the Node.js compatibility features as a whole within your Workers, you can set the nodejs_compat compatibility flag in your wrangler.jsonc or wrangler.toml configuration file. If you are not using Wrangler, you can also set the flag via the Cloudflare dashboard or API:
{
"name": "my-worker",
"main": "src/index.js",
"compatibility_date": "2025-09-21",
"compatibility_flags": [
// Get everything Node.js compatibility related
"nodejs_compat",
]
}
The compatibility date here is key! Update that to the most current date, and you’ll always be able to take advantage of the latest and greatest features.
The nodejs_compat flag is an umbrella flag that enables all the Node.js compatibility features at once. This is the recommended way to enable Node.js compatibility, as it ensures that all features are available and work together seamlessly. However, if you prefer, you can also enable or disable some features individually via their own compatibility flags:
| Module | Enable Flag (default) | Disable Flag |
|---|---|---|
| node:console | enable_nodejs_console_module | disable_nodejs_console_module |
| node:fs | enable_nodejs_fs_module | disable_nodejs_fs_module |
| node:http (client) | enable_nodejs_http_modules | disable_nodejs_http_modules |
| node:http (server) | enable_nodejs_http_server_modules | disable_nodejs_http_server_modules |
| node:os | enable_nodejs_os_module | disable_nodejs_os_module |
| node:process | enable_nodejs_process_v2 | |
| node:zlib | nodejs_zlib | no_nodejs_zlib |
| process.env | nodejs_compat_populate_process_env | nodejs_compat_do_not_populate_process_env |
By separating these features, you can have more granular control over which Node.js APIs are available in your Workers. At first, we had started rolling out these features under the one nodejs_compat flag, but we quickly realized that some users perform feature detection based on the presence of certain modules and APIs and that by enabling everything all at once we were risking breaking some existing Workers. Users who are checking for the existence of these APIs manually can ensure new changes don’t break their workers by opting out of specific APIs:
{
"name": "my-worker",
"main": "src/index.js",
"compatibility_date": "2025-09-15",
"compatibility_flags": [
// Get everything Node.js compatibility related
"nodejs_compat",
// But disable the `node:zlib` module if necessary
"no_nodejs_zlib",
]
}
But, to keep things simple, we recommend starting with the nodejs_compat flag, which will enable everything. You can always disable individual features later if needed. There is no performance penalty to having the additional features enabled.
One important difference between Node.js and Workers is that Node.js has a defined long term support (LTS) schedule that allows it to make breaking changes at certain points in time. More specifically, Node.js can remove APIs and features when they reach end-of-life (EOL). On Workers, however, we have a rule that once a Worker is deployed, it will continue to run as-is indefinitely, without any breaking changes as long as the compatibility date does not change. This means that we cannot simply remove APIs when they reach EOL in Node.js, since this would break existing Workers. To address this, we have introduced a new set of compatibility flags that allow users to specify that they do not want the nodejs_compat features to include end-of-life APIs. These flags are based on the Node.js major version in which the APIs were removed:
The remove_nodejs_compat_eol flag will remove all APIs that have reached EOL up to your current compatibility date:
{
"name": "my-worker",
"main": "src/index.js",
"compatibility_date": "2025-09-15",
"compatibility_flags": [
// Get everything Node.js compatibility related
"nodejs_compat",
// Remove Node.js APIs that have reached EOL up to your
// current compatibility date
"remove_nodejs_compat_eol",
]
}
-
The
remove_nodejs_compat_eol_v22flag will remove all APIs that reached EOL in Node.js v22. When using removenodejs_compat_eol, this flag will be automatically enabled if your compatibility date is set to a date after Node.js v22’s EOL date (April 30, 2027). -
The
remove_nodejs_compat_eol_v23flag will remove all APIs that reached EOL in Node.js v23. When using removenodejs_compat_eol, this flag will be automatically enabled if your compatibility date is set to a date after Node.js v24’s EOL date (April 30, 2028). -
The
remove_nodejs_compat_eol_v24flag will remove all APIs that reached EOL in Node.js v24. When usingremovenodejs_compat_eol, this flag will be automatically enabled if your compatibility date is set to a date after Node.js v24’s EOL date (April 30, 2028).
If you look at the date for remove_nodejs_compat_eol_v23 you’ll notice that it is the same as the date for remove_nodejs_compat_eol_v24. That is not a typo! Node.js v23 is not an LTS release, and as such it has a very short support window. It was released in October 2023 and reached EOL in May 2024. Accordingly, we have decided to group the end-of-life handling of non-LTS releases into the next LTS release. This means that when you set your compatibility date to a date after the EOL date for Node.js v24, you will also be opting out of the APIs that reached EOL in Node.js v23. Importantly, these flags will not be automatically enabled until your compatibility date is set to a date after the relevant Node.js version’s EOL date, ensuring that existing Workers will have plenty of time to migrate before any APIs are removed, or can choose to just simply keep using the older APIs indefinitely by using the reverse compatibility flags like add_nodejs_compat_eol_v24.
One other important bit of work that we have been doing is expanding Cloudflare’s investment back into the Node.js ecosystem as a whole. There are now five members of the Workers runtime team (plus one summer intern) that are actively contributing to the Node.js project on GitHub, two of which are members of Node.js’ Technical Steering Committee. While we have made a number of new feature contributions such as an implementation of the Web Platform Standard URLPattern API and improved implementation of crypto operations, our primary focus has been on improving the ability for other runtimes to interoperate and be compatible with Node.js, fixing critical bugs, and improving performance. As we continue to grow our efforts around Node.js compatibility we will also grow our contributions back to the project and ecosystem as a whole.
| Aaron Snell | 2025 Summer Intern, Cloudflare Containers Node.js Web Infrastructure Team |
 |
|---|---|---|
 |
flakey5 | |
| Dario Piotrowicz | Senior System Engineer Node.js Collaborator |
 |
|
dario-piotrowicz | |
| Guy Bedford | Principal Systems Engineer Node.js Collaborator |
 |
|
guybedford | |
| James Snell | Principal Systems Engineer Node.js TSC |
 |
|
jasnell | |
| Nicholas Paun | Systems Engineer Node.js Contributor |
 |
|
npaun | |
| Yagiz Nizipli | Principal Systems Engineer Node.js TSC |
 |
|
anonrig |
Cloudflare is also proud to continue supporting critical infrastructure for the Node.js project through its ongoing strategic partnership with the OpenJS Foundation, providing free access to the project to services such as Workers, R2, DNS, and more.
Our vision for Node.js compatibility in Workers is not just about implementing individual APIs, but about creating a comprehensive platform that allows developers to run existing Node.js code seamlessly in the Workers environment. This involves not only implementing the APIs themselves, but also ensuring that they work together harmoniously, and that they integrate well with the unique aspects of the Workers platform.
In some cases, such as with node:fs and node:crypto, we have had to implement entirely new capabilities that were not previously available in Workers and did so at the native runtime level. This allows us to tailor the implementations to the unique aspects of the Workers environment and ensure both performance and security.
And we’re not done yet. We are continuing to work on implementing additional Node.js APIs, as well as improving the performance and compatibility of the existing implementations. We are also actively engaging with the community to understand their needs and priorities, and to gather feedback on our implementations. If there are specific Node.js APIs or npm packages that you would like to see supported in Workers, please let us know! If there are any issues or bugs you encounter, please report them on our GitHub repository. While we might not be able to implement every single Node.js API, nor match Node.js’ behavior exactly in every case, we are committed to providing a robust and comprehensive Node.js compatibility layer that meets the needs of the community.
All the Node.js compatibility features described in this post are available now. To get started, simply enable the nodejs_compat compatibility flag in your wrangler.toml or wrangler.jsonc file, or via the Cloudflare dashboard or API. You can then start using the Node.js APIs in your Workers applications right away.
comments
