How we rebuilt Cloudflare Workers’ module registry for Node.js compatibility

Summary

Cloudflare has rebuilt the module registry in workerd, the open-source core of the Workers runtime, to improve speed, standards compliance, and alignment with Node.js. The change addresses compatibility beyond runtime APIs by making module resolution, loading, and caching behave more like Node.js across ESM, CommonJS, and WebAssembly. The new registry uses URLs as specifiers, supports import.meta.url, import.meta.main, and import.meta.resolve(), distinguishes modules by query strings and fragments, validates import attributes, follows require(esm) rules, and compiles modules lazily while sharing caches across isolates. It also supports WebAssembly source phase imports and consistent loading errors; the existing registry remains in place, and the new implementation must be enabled with the new_module_registry compatibility flag.

Takeaways

1. 1

   Module specifiers are parsed as URLs, so relative imports follow new URL() resolution rules; query strings and fragments create distinct module instances.

2. 2

   The registry compiles modules when first imported, whether statically or dynamically, rather than compiling the entire Worker bundle up front.

3. 3

   WebAssembly source phase imports return a WebAssembly.Module directly, but source phase imports for other module types currently throw a SyntaxError.