Skip to content
Cloudflare Docs

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
  2. As polyfills that Wrangler adds to your Worker's code when it bundles it

You can view which APIs are supported using the Node.js compatability matrix ↗.

Get Started

To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the nodejs_compat compatibility flag to your wrangler.toml, and set your compatibility date to September 23rd, 2024 or later.

compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"

Built-in Node.js Runtime APIs

The following APIs from Node.js are provided directly by the Workers Runtime when either nodejs_compat or nodejs_compat_v2 are enabled:

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

Node.js API Polyfills

When you enable the nodejs_compat compatability flag and set your compatibility date to 2024-09-23 or later, in addition to enabling Node.js APIs in the Workers Runtime, Wrangler will use unenv ↗ 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.

Where it is possible to provide a fully functional polyfill of the relevant Node.js API, unenv will do so. In cases where this is not possible, such as the fs ↗, unenv adds a module 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.

For a full list of APIs supported, including information on which are mocked, see the Node.js compatability matrix ↗.

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.

Adding Node.js polyfills yourself, via your own build process

If your Worker uses a JavaScript framework, many frameworks provide their own build command and tooling (via tools like Webpack, Rollup, or esbuild), that bundles your code into one or many files to be deployed.

In this case, instead of relying on Wrangler's bundling process to inject polyfills of Node.js APIs, you may want to add these polyfills as part of the framework's own build process, and disable Wrangler's own bundling. This can simplify your build process — rather than running the framework's build command and bundling code, and then asking Wrangler to take this output and then bundle it again itself, you only bundle your code once. If you generate and upload source maps, bundling once will ensure the generated sourcemap can be used to map your compiled code back to the original source.

How-to

  1. Install unenv:

    Terminal window
    npm install --save unenv

  2. Add unenv to your code using the Cloudflare preset:

import { env, nodeless, cloudflare } from "unenv";


const envConfig = env(nodeless, cloudflare, {});

Refer to the unenv documentation ↗ for more on how to add unenv to your application.

  1. Enable the no_bundle option in your Worker's wrangler.toml file

    no_bundle = true

  2. Run your build command, and then deploy

    Terminal window
    wrangler deploy

Enable only AsyncLocalStorage

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

compatibility_flags = [ "nodejs_als" ]
Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal