fix(cloudflare): alias debug to obug-backed shim in server environments

[nathanredblur]

Changes

astro dev with @astrojs/cloudflare currently responds with HTTP 500 on every page request:

[ERROR] [vite] Internal server error: module is not defined
    at runInRunnerObject (workers/runner-worker/index.js:106:3)
    at _NonRunnablePipeline.getComponentByRoute (.vite/deps_ssr/astro_app_entrypoint_dev.js:196:20)
    at matchRoute (.vite/deps_ssr/astro_app_entrypoint_dev.js:266:14)
    at DevApp.devMatch (.vite/deps_ssr/astro_app_entrypoint_dev.js:375:26)
    at Object.handle [as fetch] (.vite/deps_ssr/@astrojs_cloudflare_entrypoints_server.js:165:20)
    at maybeCaptureError (workers/runner-worker/index.js:50:10)

The cause is the CJS debug package. Its entrypoint (node_modules/debug/src/index.js) reads module.exports at the top level, and module is not a global in the workerd runner that @cloudflare/vite-plugin uses for astro dev, SSR and prerender environments, so evaluation throws ReferenceError: module is not defined.

#15565 already addressed this for astro core by replacing its own debug usage with obug (an ESM fork) and documented adding a Vite alias for the rehype/remark rabbit hole. In practice though, debug is pulled by a much broader set of transitive dependencies — e.g. micromark (via @astrojs/markdown-remark → remark-parse → mdast-util-from-markdown), stylus (via Vite's peer dep), and many others — so any Astro 6 project that uses markdown content or stylus transitively still crashes on every request.

This PR extends the fix to user dependency graphs by aliasing debug to an adapter-owned ESM shim in the Vite config the adapter installs. The shim forwards to obug and also re-exposes a default export, because consumers do import debug from "debug" or require("debug") and obug only ships named exports.

What the shim looks like

// packages/integrations/cloudflare/src/shims/debug.ts
import { createDebug, disable, enable, enabled, namespaces } from 'obug';

export default createDebug;
export { createDebug, disable, enable, enabled, namespaces };

Where the alias is applied

Top-level vite.resolve.alias inside the adapter's astro:config:setup hook, so it propagates to every Vite environment created by the adapter (astro, ssr, prerender):

const debugShim = fileURLToPath(new URL('./shims/debug.js', import.meta.url));

updateConfig({
  // ...
  vite: {
    resolve: {
      alias: { debug: debugShim },
    },
    plugins: [ /* ... */ ],
  },
});

obug is added as a direct dependency of @astrojs/cloudflare so the shim resolves inside the adapter's own package scope regardless of hoisting.

Reproduction

Minimal reproduction — any Astro 6 project using @astrojs/cloudflare@13 with Markdown content or stylus in its dep tree will hit this. Starting from npm create astro@latest with the Cloudflare adapter and one markdown page under src/content/ is enough.

Testing

• Manually verified against a real production blog (Astro 5 → 6 migration in progress, adapter @astrojs/cloudflare@13.3.0, Node 22.22.2). Before the patch: /, /blog/, /posts/:slug/, /about/, /archive/, /projects/ all return HTTP 500 with the module is not defined trace above. With the built adapter dropped into node_modules and no other workaround: all the same routes return HTTP 200 with full content.
• Verified pnpm --filter @astrojs/cloudflare build:ci produces the expected dist/shims/debug.js alongside the patched dist/index.js.
• A dedicated unit test is tricky here because the failure only manifests when the workerd runner attempts to evaluate a module whose dep graph reaches debug; happy to add an integration test under packages/integrations/cloudflare/test/fixtures/ modelled after astro-dev-platform/code-test.astro if maintainers want one — just point me at the preferred shape.

Related

• Astro v6 with cloudflare adapter does not work with <Code ...> components #15284 — original "Astro v6 with cloudflare adapter does not work with <Code> components" issue (closed)
• fix(core): logging overhaul #15565 — original logging overhaul that replaced astro core's debug with obug
• Shadcn Svelte + Cloudflare Adapter + Astro 6 results in bad compilation of .svelte.js files in dependencies #15906 — same workerd-runner class of failure, Svelte path
• expressive-code/expressive-code#439 — same error reported against expressive-code; upstream cause is the same.

Docs

N/A — internal adapter behavior change, transparent to users.

[changeset-bot]

🦋 Changeset detected

Latest commit: 49329fa

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ocavue]

Based on obug's README, obug v2 is not a drop-in replacement for debug. Adding resolve here might break users' apps in unexpected ways. I'd recommend letting users do the replacement themselves, not in the @astro/cloudflare package

[ocavue]

Hopefully, we can persuade the upstream micromark to use obug directly in micromark/micromark#218, without doing the patch on the Astro side.

[rururux]

astro dev with @astrojs/cloudflare currently responds with HTTP 500 on every page request:

Minimal reproduction — any Astro 6 project using @astrojs/cloudflare@13 with Markdown content or stylus in its dep tree will hit this. Starting from npm create astro@latest with the Cloudflare adapter and one markdown page under src/content/ is enough.

I was unable to reproduce the issue.
Since there are no tests included, it's unclear what environment this issue reproduces in.

Additionally, as @ocavue noted in their review, I don't believe this is a safe approach for Astro to take.
I'll go ahead and close this PR for now. Thank you for your contribution.

[nathanredblur]

Thanks for the feedback.
I understand the concern about obug not being a strict drop-in replacement.

For anyone hitting the ReferenceError: module is not defined crash during an Astro 5 → 6 migration with @astrojs/cloudflare, you can apply the alias manually at the project level as a workaround until this is resolved upstream. Here's how I did it in my own migration:

nathanredblur/nathanredblur.dev@db7b501

The key is adding obug as a direct dependency and aliasing debug to a small shim in your astro.config.* — keeping it project-scoped rather than adapter-scoped, which avoids the safety concern raised here.

astro.config.mjs‎

  vite: {
    plugins: [tailwindcss()],
    resolve: {
      alias: {
        debug: new URL("./src/shims/debug.js", import.meta.url).pathname,
      },
    },

src/shims/debug.js‎

import { createDebug, disable, enable, enabled, namespaces } from "obug";

export default createDebug;
export { createDebug, disable, enable, enabled, namespaces };