Some Node.js-dependent packages can run on Cloudflare Workers, but npm installation or a successful import does not prove compatibility. Check the exact Node.js APIs your dependency versions use, confirm your Worker’s compatibility date and flags, and test the code in a Workers environment before deploying.
Will my npm package work on Cloudflare Workers?
It depends on the package’s actual runtime behavior, not just its name or whether it installs. Cloudflare implements a subset of Node.js APIs in the Workers Runtime; some are only partially supported. Wrangler can also provide polyfill shims that let certain imports resolve even when the corresponding methods do not work as the package expects. See Cloudflare’s Node.js compatibility documentation for the current API list and status labels.
As an Amazon Associate I earn from qualifying purchases.
Compatibility is therefore specific to the package version, the code paths your application exercises, and your Worker configuration. A dependency might work for one feature and fail when another feature calls an unsupported API. There is no documented percentage of npm packages that work on Workers, and without a specific dependency tree and project configuration, a blanket yes or no would be misleading.
How do I check whether a dependency is compatible with Workers?
- Identify what the package uses. Check the versions in your lockfile and inspect the package’s documented requirements and runtime imports. Include indirect dependencies where practical. Look for Node.js built-ins and the specific methods or features the package calls; the module name alone may not reveal whether your application uses an unsupported part of it.
- Compare those APIs with Cloudflare’s current list. In the Node.js compatibility documentation, distinguish APIs marked supported from those marked partially supported and from non-functional stubs. A stub or shim may satisfy an import or feature check without providing useful functionality. Verify the methods your dependency actually calls.
- Check your Worker’s compatibility configuration. Find
compatibility_dateandcompatibility_flagsin your Wrangler configuration. The date determines whether Node.js compatibility is enabled by default or requires an explicit flag. - Exercise the dependency in a Worker, not only in Node.js. Run the project’s tests and representative local Worker executions with your current Cloudflare toolchain. Add targeted checks for partially supported APIs and any Node.js testing features your tests rely on.
- Change the date deliberately, then test and deploy. Review the effects of a newer compatibility date, run tests, and deploy only after validating the change. If a package still errors with a current compatibility date and updated Wrangler or Cloudflare Vite Plugin, Cloudflare’s compatibility documentation suggests reporting the issue.
Do I need nodejs_compat?
As of October 4, 2026, the default depends on the Worker’s compatibility date. Cloudflare’s August 4, 2026 changelog says dates on or after 2026-08-04 enable both nodejs_compat and nodejs_compat_v2 by default. For dates from 2024-09-23 through 2026-08-03, add nodejs_compat to opt in. Older configurations have a different flag history, so check Cloudflare’s compatibility flags documentation rather than assuming the current rules apply.
#1 Best Overall
For dates on or after 2026-08-04, Cloudflare documents a separate opt-out path: remove positive Node.js compatibility flags and add both no_nodejs_compat and no_nodejs_compat_v2. Because this behavior depends on the compatibility date and flags, verify the current documentation before changing a production configuration.
Why isn’t a Node.js test enough?
A test passing under ordinary Node.js shows that the tested code works in that environment; it does not establish that the Workers Runtime implements the same APIs or behavior. Workers-specific tests can expose gaps in the runtime or its test APIs. For example, Cloudflare’s Node.js test documentation says its implementation of Node.js MockTracker does not include mock timers. If a test depends on mock timers, account for that limitation rather than treating the test failure as proof that the deployed dependency itself is incompatible.
Should I update the compatibility date?
Cloudflare recommends setting a new project’s compatibility_date to the current date in its compatibility-dates guidance. For an existing project, review the compatibility changes and flags before updating. The new date takes effect on the next npx wrangler deploy, and Cloudflare says older compatibility dates remain supported. A newer date can change runtime behavior, so test the application against it before deploying; it is not a guarantee that every package will work.
Recommended Free Tools
What to conclude from your check
You have stronger evidence for deployment when the exact APIs used by your dependency versions are supported, the Worker has the intended compatibility settings, and representative code paths pass in a Workers environment. Treat partial support, shims, stubs, and untested features as specific risks to resolve—not as a general pass based on successful installation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
