Skip to content

Node.js compatibility

Most Workers import one or more packages of JavaScript or TypeScript code from npm as dependencies in package.json. Many of these packages rely on APIs from the Node.js runtime, and will not work unless these APIs are present.

To ensure compatibility with a wider set of npm packages, and make it easier for you to run existing applications on Cloudflare Workers, the following APIs from the Node.js runtime are available directly as Workers runtime APIs, with no need to add polyfills to your own code:

Node.js APIs are available under the node: prefix, and this prefix must be used when importing modules, both in your code and the npm packages you depend on.

// Do this:
import { Buffer } from 'node:buffer';
// Do not do this:
import { Buffer } from 'buffer';

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

Enable Node.js with Workers

Add the nodejs_compat compatibility flag to your wrangler.toml:

wrangler.toml
compatibility_flags = [ "nodejs_compat" ]

Enable Node.js with Pages Functions

Enable Node.js with Wrangler

To enable nodejs_compat in local development, pass the --compatibility-flags argument with the nodejs_compat flag to wrangler pages dev:

Terminal window
$ npx wrangler pages dev [<DIRECTORY>] --compatibility-flags="nodejs_compat"

For additional options, refer to the list of Pages-specific CLI commands.

Enable Node.js from the Cloudflare dashboard

To enable Node.js for your Pages Function from the Cloudflare dashboard:

  1. Log in to the Cloudflare dashboard and select your account.
  2. Select Workers & Pages and in Overview, select your Pages project.
  3. Select Settings > Functions > Compatibility Flags.
  4. Add the nodejs_compat compatibility flag to your Preview and Production deployments.

Enable only AsyncLocalStorage

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

compatibility_flags = [ "nodejs_als" ]