Cloudflare Workers Compatibility Checker for npm

How the checker reads a package

Nothing leaves the page until you press Check packages. Then, for each package, the checker asks the npm registry for the newest version your range allows, the same one a fresh install picks, and asks jsDelivr for that version's file list.

From the file list and the package's manifest it finds the file Wrangler would bundle. Wrangler builds with esbuild and sets the workerd, worker and browser conditions, so in a package's exports the checker takes the first key among those, import and default, in the order the package lists them. A package without exports falls back to its browser, module and main fields, in that order, and a browser map that swaps a file or switches a module off is applied too.

It then reads that entry file and the files it imports inside the same package, up to a cap, and collects every import, export … from, require() and import() with a fixed string. A require inside a try block or a dynamic import() counts as optional, because a package that guards a Node.js import usually has a fallback.

Before reading any code, it looks for signs of native code: a .node file or binding.gyp in the package, an install script that runs node-gyp or prebuild-install, a dependency on a native loader such as node-gyp-build, a set of per-platform binary packages in optionalDependencies, or an os or cpu list that limits where it installs.

What the five results mean

Runs as is. The entry files import no Node.js built-in and nothing native turned up. Many packages written for browsers or for several runtimes land here, and some ship a build just for Workers under the workerd or worker condition.

Needs Node.js compatibility. The package imports at least one Node.js module. The result says which ones, in which file, and the first compatibility date on which all of them work.

Loads, some calls fail. The package also imports a module that Workers ship only as a stub, such as node:child_process. It loads, but whatever calls into that module throws. That can be one transport you never use, as with nodemailer's sendmail, or the whole point of the package, as with execa.

Will not run. The package needs native code, or drives a browser on the same machine as Puppeteer and Playwright do, so no compatibility date or flag will make it work. The Workers option beside it points to the Cloudflare product that covers the same job where one is well known.

Could not tell. npm does not know the package or version, the version is local such as workspace: or file:, the package has no entry file to import, its entry file is too large to read here, or it is a Nuxt module.

The compatibility date and nodejs_compat

compatibility_date pins the version of the Workers runtime your Worker runs on, and compatibility_flags turn single changes on or off around it. Node.js support is one of those changes, and several Node.js modules arrived on later dates, so the checker works out the earliest date that covers every module the packages import.

For a new project, the settings use today's date, which already turns Node.js compatibility on, so they need no flag. A project that stays on a date from before that default needs the flag, like this:

{
  "compatibility_date": "2026-03-17",
  "compatibility_flags": ["nodejs_compat"],
}

If you keep an older date, type it in. The checker keeps it when it is new enough, adds nodejs_compat when the date needs it, and otherwise says which date to move to, or which enable_nodejs_…_module flags would keep your date working instead.

Static detection has limits

The checker never runs the code. It sees imports written as plain strings, not modules picked at runtime, Node.js globals such as Buffer or __dirname used without an import, or which branch of a package your app reaches. It reads only the packages you list, so a dependency of a dependency that needs Node.js stays invisible unless you add it by name. It also stops after a fixed number of files per package and says so.

Frameworks and build tools such as Nuxt, Vite and Wrangler run at build time, so the checker skips them along with type packages. A framework that targets Workers is judged by what its build puts in the bundle, not by its package entry. A Nuxt module, such as @nuxt/ui, is the same case: its entry runs in the Nuxt build and imports Node.js freely, while the runtime code it adds is bundled by Nitro, so it reads as could not tell rather than as a false alarm.