Node.js compatibility

When you write a Worker, you may need to import packages from npm ↗. Many npm packages rely on APIs from the Node.js runtime ↗, and will not work unless these Node.js APIs are available.

Cloudflare Workers provides a subset of Node.js APIs in two forms:

1. As built-in APIs provided by the Workers Runtime. Most of these APIs are full implementations of the corresponding Node.js APIs, while a few are partially supported.
2. As polyfill shim implementations that Wrangler adds to your Worker's code, allowing it to import the module, but calling API methods will throw errors.

To enable built-in Node.js APIs and add polyfills, add the nodejs_compat compatibility flag to your Wrangler configuration file, and ensure that your Worker's compatibility date is 2024-09-23 or later. Learn more about the Node.js compatibility flag and v2.

{
  "compatibility_flags": ["nodejs_compat"],
  // Set this to today's date
  "compatibility_date": "2026-07-01",
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-07-01"

The runtime APIs from Node.js listed in this section with the status "🟢 supported" are currently natively supported in the Workers Runtime. Items listed as "🟡 partially supported" include usable APIs, but do not implement the complete Node.js API surface.

Deprecated or experimental APIs from Node.js ↗, and APIs that do not fit in a serverless context, are not included in the supported API list in this section. Some import-only stubs for these APIs are listed separately in Non-functional stub modules.

Unless otherwise specified, native implementations of Node.js APIs in Workers are intended to match the implementation in the Current release of Node.js ↗.

If an API you wish to use is missing and you want to suggest that Workers support it, please add a post or comment in the Node.js APIs discussions category ↗ on GitHub.

Some Node.js modules are available as non-functional stubs. A stub can be imported or required, but does not provide a working implementation of the underlying Node.js API. These stubs exist so packages that check for the presence of a module can load in Workers, but they are not suitable for direct use in application code.

The following stubs are enabled automatically only when the nodejs_compat compatibility flag is enabled and your Worker's compatibility date is on or after the date shown. To enable one earlier, add the corresponding enable flag. To keep one unavailable after that date, add the corresponding disable flag.

Node.js APIs that are not yet supported in the Workers runtime are polyfilled via Wrangler, which uses unenv ↗. If the nodejs_compat compatibility flag is enabled, and your Worker's compatibility date is 2024-09-23 or later, Wrangler will automatically inject polyfills into your Worker's code.

Adding polyfills maximizes compatibility with existing npm packages by providing modules with mocked methods. Calling these mocked methods will either noop or will throw an error with a message like:

[unenv] <method name> is not implemented yet!

This allows you to import packages that use these Node.js modules, even if certain methods are not supported.

If you need to enable only the Node.js AsyncLocalStorage API, you can enable the nodejs_als compatibility flag:

{
  "compatibility_flags": ["nodejs_als"],
}

compatibility_flags = [ "nodejs_als" ]