Node.js compatibility

When you write a Worker, you may need to import packages from npm Open external link . Many npm packages rely on APIs from the Node.js runtime Open external link , 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
2. As polyfills, added to your code by Wrangler (or by your own build tools)

To enable both built-in APIs and polyfills to your Worker, add the experimental:nodejs_compat_v2 compatibility flag to your wrangler.toml:

wrangler.toml
compatibility_flags = [ "experimental:nodejs_compat_v2" ]

​​ Built-in Node.js Runtime APIs

The following APIs from Node.js are provided directly by the Workers Runtime:

• assert
• AsyncLocalStorage
• Buffer
• Crypto
• Diagnostics Channel
• EventEmitter
• path
• process
• Streams
• StringDecoder
• test
• util

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

​​ Node.js API Polyfills

When you build your Worker with Wrangler, and enable the experimental:nodejs_compat_v2 compatibility flag, in addition to enabling built-in Node.js APIs from the Workers Runtime, Wrangler will use unenv Open external link to automatically detect uses of Node.js APIs, and add polyfills where relevant.

Adding polyfills maximizes compatibility with existing npm packages, while recognizing that not all APIs from Node.js make sense in the context of serverless functions.

In cases where it is possible to provide a polyfill version of the relevant Node.js API, unenv will do so. In cases where it is not possible to provide a polyfill, such as the fs module, unenv adds the module and its methods to your Worker, but calling methods of the module will either noop, or will throw an error with a message like:

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

​​ Adding polyfills to your Worker manually

If you do not use Wrangler to bundle your Worker, and instead use the build tooling provided by a framework such as Next.js, Remix, or Astro, you will need to add polyfills yourself. Follow the unenv docs Open external link for guidance on how to integrate unenv with your bundler or build tool of choice.

​​ Enable only AsyncLocalStorage

To enable the Node.js AsyncLocalStorage API only, use the nodejs_als compatibility flag.

wrangler.toml
compatibility_flags = [ "nodejs_als" ]