← Back to all posts

Test Worker Module Loading Before Changing Your Compatibility Date

Use a small local Worker to separate module loading from bundling, and see why import.meta.resolve is not a file-existence check.

A softly modeled orange Cloudflare Workers mark

Your Worker imports a helper successfully. Does that prove its module loader can resolve another file? And if the loader returns a URL, does the file actually exist?

A tiny fixture makes those questions visible before you change a compatibility setting in a larger app. The important split is between the modules your build uploads and the operations the runtime performs on those modules.

A build produces the uploaded module graph, which is then resolved by the Worker runtime

A date can change runtime behavior

Cloudflare’s November 2 notice says JavaScript Workers using a compatibility date of November 17, 2026 or later will use the new module registry by default. Existing Workers retain their behavior until their date or flags change; Python Workers use the legacy registry.

That is a configuration boundary, not a date when every existing deployment switches at once.

The bundling documentation adds another boundary: build tools can transform module expressions before the runtime sees them. Inspecting a bundled app alone can conceal which layer supplied a behavior.

Make resolution observable

Create two files in a disposable directory. In helper.js:

export const message = "helper loaded";

In index.js:

import { message } from "./helper.js";

export default {
  fetch() {
    return Response.json({
      message,
      moduleUrl: import.meta.url ?? null,
      isEntrypoint: import.meta.main ?? null,
      helperUrl:
        typeof import.meta.resolve === "function"
          ? import.meta.resolve("./helper.js")
          : null,
      missingUrl:
        typeof import.meta.resolve === "function"
          ? import.meta.resolve("./not-present.js")
          : null,
    });
  },
};

Do not create not-present.js. The final field is the interesting part.

For an unbundled fixture, explicitly include the additional module. Save wrangler.json:

{
  "name": "blog-module-fixture",
  "main": "index.js",
  "compatibility_date": "2026-11-05",
  "compatibility_flags": ["new_module_registry"],
  "find_additional_modules": true,
  "rules": [{ "type": "ESModule", "globs": ["**/*.js"], "fallthrough": true }]
}

Run the pinned version used for this experiment:

npx wrangler@4.157.0 dev --local --ip 127.0.0.1 --port 8794 --no-bundle

In another terminal:

curl http://127.0.0.1:8794/

Stop the server with Ctrl+C when finished. Compare it with a separate run using legacy_module_registry, keeping the other settings fixed. These flags are alternatives for the experiment, not a pair to enable together.

The missing file still gets a URL

Local tests on November 5, 2026, with Wrangler 4.157.0 produced this contrast:

Observation Legacy, unbundled New registry, unbundled
Static helper import helper loaded helper loaded
Module URL null file:///bundle/index.js
Entry-point field null true
Existing helper resolution null file:///bundle/helper.js
Missing helper resolution null file:///bundle/not-present.js

The null values come from the fixture’s guards. They are not a universal description of every legacy module expression.

Recorded local responses show the new registry resolving both an existing and a nonexistent helper URL

Wrangler local fixture results; no production Worker was deployed.

The new resolver returned a URL for a module we never supplied. Resolution is not loading, fetching, or checking existence. Cloudflare explicitly documents that distinction in the notice.

A third, bundled run with the new registry gave the same response for this fixture. That is useful evidence about these files and this tool version, not proof that bundling never changes module behavior.

Carry the small test into the upgrade

Replace the helper with the dependency behavior you actually rely on. Record the current date, flags, build settings, and result; then change one setting and compare. For example, Cloudflare documents restrictions on require() loading ES modules whose dependency graph uses top-level await. That needs its own fixture; the one above does not test it.

If the basic Worker development loop is new, the LabEx Cloudflare path includes local testing and configuration practice. Use that foundation before interpreting loader differences.

Keep local and remote evidence separate. A local success is a reason to continue controlled validation, not a claim that the deployed app’s complete module graph has been exercised.

References