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

Fixes `ReferenceError: module is not defined` on every request in
`astro dev` with the Cloudflare adapter. The CJS `debug` package is
pulled transitively by `micromark`, `stylus`, and many other common
npm packages; when `@cloudflare/vite-plugin` loads it in the workerd
runner used for `astro dev`, SSR and prerendering, the top-level
`module.exports` reference crashes because `module` is not a global
there.

Extends the approach from #15565 (which replaced astro core's direct
`debug` usage with `obug`) to the downstream dependency graph by
aliasing `debug` to an internal shim that re-exports `obug` with a
default export, so consumers that do `import debug from "debug"` or
`require("debug")` keep working after the alias is applied.

The alias is added at the top-level `vite.resolve.alias` so it
propagates to every Vite environment created by the adapter (astro,
ssr, prerender).

Author: nathanredblur

.changeset/cloudflare-debug-alias.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/cloudflare': patch
+---
+
+Fixes `ReferenceError: module is not defined` on every request when running `astro dev` with the Cloudflare adapter. The error was triggered whenever a page's dependency graph pulled in the CJS `debug` package (transitively via `micromark`, `stylus`, and many other common npm packages). The adapter now aliases `debug` to an internal ESM shim backed by `obug` in the `ssr`, `astro`, and `prerender` Vite environments, so the workerd runner used by `@cloudflare/vite-plugin` no longer hits the missing `module` global.

packages/integrations/cloudflare/package.json

@@ -45,6 +45,7 @@
     "@astrojs/internal-helpers": "workspace:*",
     "@astrojs/underscore-redirects": "workspace:*",
     "@cloudflare/vite-plugin": "^1.32.3",
+    "obug": "^2.1.1",
     "piccolore": "^0.1.3",
     "tinyglobby": "^0.2.15",
     "vite": "^7.3.2"

packages/integrations/cloudflare/src/index.ts

@@ -1,6 +1,7 @@
 import { createReadStream, existsSync, readFileSync } from 'node:fs';
 import { appendFile, rename, stat } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
 import { removeLeadingForwardSlash } from '@astrojs/internal-helpers/path';
 import { createRedirectsFromAstroRoutes, printAsRedirects } from '@astrojs/underscore-redirects';
 import { cloudflare as cfVitePlugin, type PluginConfig } from '@cloudflare/vite-plugin';
@@ -206,12 +207,24 @@ export default function createIntegration({
 					globalThis.astroCloudflareOptions = cfPluginConfig;
 				}
 
+				// Replace the CJS `debug` package (pulled transitively by
+				// `micromark`, `stylus`, and many other npm packages) with an
+				// ESM-compatible shim backed by `obug`. The original `debug`
+				// references `module.exports` at the top level, which fails
+				// with `ReferenceError: module is not defined` when
+				// @cloudflare/vite-plugin loads it in the workerd runner used
+				// for `astro dev`, SSR and prerendering.
+				const debugShim = fileURLToPath(new URL('./shims/debug.js', import.meta.url));
+
 				updateConfig({
 					build: {
 						redirects: false,
 					},
 					session,
 					vite: {
+						resolve: {
+							alias: { debug: debugShim },
+						},
 						plugins: [
 							...(prerenderEnvironment === 'node' && command === 'dev'
 								? [createNodePrerenderPlugin()]

packages/integrations/cloudflare/src/shims/debug.ts

@@ -0,0 +1,16 @@
+// Drop-in ESM replacement for the `debug` package, used via Vite's
+// `resolve.alias` in server environments that run under workerd
+// (astro dev + @cloudflare/vite-plugin).
+//
+// The original `debug` package references `module.exports` at the top
+// level of its CJS entrypoint, which throws `ReferenceError: module is
+// not defined` when @cloudflare/vite-plugin loads it in the Workers
+// runner. `obug` (https://www.npmjs.com/package/obug) is an ESM fork
+// with the same behavior but exposes only named exports; this shim
+// re-exposes a default export so consumers that do
+// `import debug from "debug"` or `const debug = require("debug")`
+// keep working after the alias is applied.
+import { createDebug, disable, enable, enabled, namespaces } from 'obug';
+
+export default createDebug;
+export { createDebug, disable, enable, enabled, namespaces };