Cloudflare Workers overhauls Node.js module registry

Cloudflare has replaced the module registry in its open-source Workers runtime, workerd, to better align with Node.js standards. The update introduces a new compatibility flag that developers must enable to access the improved module resolution system. This change allows Workers to handle larger Node.js applications—up to 64 MiB on all plans—without requiring compressed bundle size limits previously in place.

The new registry addresses long-standing inconsistencies in how Workers resolved modules compared to Node.js. Previously, the runtime treated specifiers as filesystem-style paths, which created friction for features like import.meta.resolve() and relative imports. The updated implementation now parses specifiers as URLs, enabling support for query strings, fragments, and protocols such as node: and cloudflare:. This shift also introduces lazy compilation, reducing upfront processing overhead and memory usage across multiple V8 isolates running the same Worker.

How the new registry works

The updated module registry introduces several key behaviors that mirror Node.js conventions. Static and dynamic imports now resolve specifiers identically to new URL(), including support for query strings and fragments. For example, importing ./counter.js?a and ./counter.js?b loads the same source file but treats them as separate module instances, each with its own state. This aligns with browser module identity rules and prevents unintended state sharing.

Import attributes are now strictly validated. The registry enforces the type: 'json' attribute for JSON modules and rejects unsupported attributes like cache: 'no' with a TypeError. Similarly, requiring an ES module from CommonJS follows Node.js rules: if the module exports a string-named module.exports, that value is returned; otherwise, the namespace object is provided. Top-level await in required modules throws an error, as Node.js does, to maintain synchronous require() behavior.

Error handling has been standardized across static imports, dynamic import(), and require(). Failures now return consistent error classes and messages, regardless of the loading path. For instance, a missing module throws a plain Error, while an invalid specifier triggers a TypeError. This consistency simplifies debugging and allows tools like loaders or retry wrappers to handle errors predictably.

WebAssembly modules gain support for source phase imports, enabling direct access to the compiled-but-not-instantiated form of a module. This feature, available via import.source or dynamic import.source(), returns a WebAssembly.Module object, streamlining integration with WebAssembly workflows.

Impact on developers and tooling

The new registry reduces the need for bundlers like esbuild and Rolldown to perform extensive transformations. When using the Cloudflare Vite plugin, Rolldown can now emit a smaller, build-generated module graph, relying more on the runtime for resolution. Developers deploying with --no-bundle or uploading multiple modules directly will see their module graphs preserved exactly as written, without inlining or path rewrites.

Cloudflare has not set a default enablement date for the new registry, so developers must add the new_module_registry compatibility flag to their Worker configuration to use it. The company has published detailed reference documentation in the workerd repository for those needing deeper technical insights.

What’s next

The updated registry is available now for testing. Cloudflare encourages developers to provide feedback, particularly on edge cases or regressions, through the workerd GitHub repository. The company has stated that the original registry implementation will remain in place indefinitely, ensuring backward compatibility for existing deployments.