[Cloudflare] External WASM assets are emitted to dist/client and inaccessible to Worker in Astro 6

[shindgewongxj]

Astro Info

Astro                    v6.0.0-beta.6
Vite                     v7.3.1
Node                     v25.6.1
System                   macOS (arm64)
Package Manager          npm
Output                   server
Adapter                  @astrojs/cloudflare (v13.0.0-beta.3)
Integrations             @astrojs/mdx (v5.0.0-beta.3)
                         @astrojs/react (v4.4.2)
                         @astrojs/sitemap (v3.6.1-beta.2)

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

I am upgrading a project from Astro 5 to Astro 6 using the @astrojs/cloudflare adapter. My project relies on the library(https://developers.cloudflare.com/pages/functions/plugins/vercel-og) that loads a .wasm file at runtime.

In Astro 5:
The build process seemed to bundle or place the WASM file in a location accessible to the Worker script, or the single dist structure allowed relative path resolution.

In Astro 6:
The .wasm file is strictly emitted to dist/client/_astro/file.wasm.
However, the server logic (the Worker) is compiled to dist/_worker.js.

When the Worker runs on Cloudflare, it crashes because it attempts to load the WASM file, but the file is not bundled into the Worker, nor is it accessible via the relative path expected by the library.

What's the expected result?

Server-side dependencies that require WASM should either:

• Be automatically bundled into the _worker.js (if small enough).
• Or, the adapter should provide a mechanism to map these assets so the Worker can resolve them from the client assets folder at runtime.

Link to Minimal Reproducible Example

https://stackblitz.com/afk-and-will-update-soon

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

I was able to reproduce this issue. When using the @astrojs/cloudflare adapter with a WASM file referenced via new URL('./file.wasm', import.meta.url), the WASM file is completely missing from the build output — it does not appear in dist/client/ or dist/_worker.js/, and the new URL() expression is left verbatim in the worker code, causing a runtime crash on Cloudflare Workers.

Fix: I was able to fix this issue. A new Vite plugin (@astrojs/cloudflare:wasm-url) was added to the Cloudflare adapter that replicates Vite's assetImportMetaUrlPlugin behavior for the SSR environment. It detects new URL('./file.wasm', import.meta.url) patterns, emits the referenced WASM file as a hashed static asset, and rewrites the URL so the Worker can resolve it at runtime via Cloudflare's asset serving. View Fix

Cause: Vite's built-in assetImportMetaUrlPlugin only runs for client environments (consumer === "client"), so new URL('./file.wasm', import.meta.url) patterns in SSR builds are left untransformed and the referenced files are never emitted — which is fine for Node.js servers (where import.meta.url resolves to filesystem paths) but breaks Cloudflare Workers (which have no filesystem access).

Impact: Any Cloudflare adapter user whose server-side code (or dependencies) loads WASM files via the new URL('./file.wasm', import.meta.url) pattern — commonly used by libraries like @vercel/og and similar OG image generators — will get a runtime crash after deploying to Cloudflare. Direct ESM import of .wasm files is unaffected.

Full Triage Report

Issue Summary

Title: [Cloudflare] External WASM assets are emitted to dist/client and inaccessible to Worker in Astro 6

Reporter's Environment:

• Astro v6.0.0-beta.6
• Vite v7.3.1
• Node v25.6.1
• macOS (arm64)
• Adapter: @astrojs/cloudflare v13.0.0-beta.3
• Integrations: @astrojs/mdx, @astrojs/react, @astrojs/sitemap
• Output: server

Bug Description:
The reporter is upgrading from Astro 5 to Astro 6 with the @astrojs/cloudflare adapter. Their project uses a library (based on the Cloudflare Pages @vercel/og plugin) that loads a .wasm file at runtime using the new URL('./file.wasm', import.meta.url) pattern. In Astro 6, the WASM file is not emitted anywhere in the build output, and the new URL() expression is left verbatim (untransformed) in the Worker code, causing a runtime crash on Cloudflare Workers.

Expected Behavior:
Server-side dependencies that require WASM should either:

• Be automatically bundled into the _worker.js (if small enough), or
• The adapter should provide a mechanism to map these assets so the Worker can resolve them from the client assets folder at runtime.

StackBlitz URL: Placeholder ("afk-and-will-update-soon") — not a real reproduction.

Relevant Comments:

• A previous triage run (astrobot-houston) successfully reproduced this issue and proposed a fix via a new Vite plugin in the Cloudflare adapter.
• FredKSchott noted the previous triage run was unusual and may need a second pair of eyes, keeping the "needs triage" label.

Reproduction

Status: REPRODUCED

Environment Used

• Astro: workspace version (from monorepo, latest)
• @astrojs/cloudflare: workspace version (from monorepo, latest)
• Node.js: Current CI runner version
• Package Manager: pnpm

Steps to Reproduce

1. Created a minimal Astro project from examples/minimal template in triage/issue-15511/
2. Configured astro.config.mjs with output: 'server' and @astrojs/cloudflare adapter
3. Created a minimal valid WASM binary (src/lib/sample.wasm) — a 41-byte module exporting an add function
4. Created src/lib/load-wasm.js that references the WASM file using new URL('./sample.wasm', import.meta.url) — the same pattern used by libraries like @vercel/og
5. Created src/pages/index.astro that imports and uses getWasmUrl() from the load-wasm module
6. Ran astro build

Results

Build succeeds but output is broken:

1. No .wasm file anywhere in dist/ — find triage/issue-15511/dist -name "*.wasm" returns nothing. The WASM file is completely absent from both dist/client/ and dist/_worker.js/.

2. new URL() expression left verbatim in worker code — In dist/_worker.js/chunks/index_LTOYt5qe.mjs (line 5):

   const wasmUrl = new URL("./sample.wasm", import.meta.url);

   This is the exact source pattern, untransformed. On Cloudflare Workers (which have no filesystem), import.meta.url won't resolve to a filesystem path, and the ./sample.wasm file doesn't exist anywhere the Worker can access it.

3. Full dist file listing:

   dist/_routes.json
   dist/_worker.js/chunks/_virtual_astro_server-island-manifest_ChL9HggY.mjs
   dist/_worker.js/chunks/_virtual_astro_session-driver_Csu6PJY6.mjs
   dist/_worker.js/chunks/astro-component_BlSOnY_1.mjs
   dist/_worker.js/chunks/image-endpoint_CuYiOB_s.mjs
   dist/_worker.js/chunks/index_LTOYt5qe.mjs
   dist/_worker.js/chunks/noop-entrypoint_DsBX4kaI.mjs
   dist/_worker.js/chunks/sharp_CJc7DUA1.mjs
   dist/_worker.js/chunks/worker-entry_CDnUmYK0.mjs
   dist/_worker.js/entry.mjs
   dist/_worker.js/virtual_astro_middleware.mjs
   dist/_worker.js/wrangler.json
   dist/client/.assetsignore
   dist/client/favicon.ico
   dist/client/favicon.svg
   

Baseline Verification

Removed the WASM import from the page and confirmed the project builds and functions correctly without it. The issue is specifically caused by the new URL('./file.wasm', import.meta.url) pattern in SSR code with the Cloudflare adapter.

Root Cause Analysis

Vite's built-in assetImportMetaUrlPlugin has an applyToEnvironment filter (consumer === "client") that restricts it to client-side builds only. During SSR builds, new URL('./file.wasm', import.meta.url) patterns pass through completely untouched, and the referenced files are never emitted via Rollup's asset pipeline.

This is intentional for Node.js servers where import.meta.url resolves to filesystem paths (so the file can be read from disk at runtime). However, it breaks Cloudflare Workers which:

• Have no filesystem access
• Cannot resolve relative paths from import.meta.url to local files
• Need all assets to be either bundled into the Worker or served as static assets via Cloudflare's CDN

Impact

Any Cloudflare adapter user whose server-side code (or dependencies) loads WASM files via the new URL('./file.wasm', import.meta.url) pattern will get a runtime crash after deploying. This is a common pattern used by:

• @vercel/og and similar OG image generators
• Any library that loads WASM at runtime using the standard Vite-compatible URL pattern

Direct ESM import of .wasm files is likely unaffected (that goes through a different code path).

Fix Direction

The previous triage comment proposed a Vite plugin (@astrojs/cloudflare:wasm-url) that:

1. Applies only to the ssr environment
2. Detects new URL('./file.wasm', import.meta.url) patterns using a regex
3. Reads the referenced file and emits it via Rollup's this.emitFile()
4. Rewrites the URL to use Vite's __VITE_ASSET__ placeholder
5. Vite's existing asset plugin resolves the placeholder to the correct hashed path (e.g., /_astro/sample.BYieBQW-.wasm)

The fix would be in:

• New file: packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts
• Modified file: packages/integrations/cloudflare/src/index.ts (to register the plugin)

A branch with a proposed fix exists at: flue/fix-15511

Diagnosis (Independent Verification)

Verification Method

Added a debug Vite plugin to the Cloudflare adapter (packages/integrations/cloudflare/src/index.ts) that intercepts the SSR transform phase and logs when new URL(...wasm..., import.meta.url) patterns are encountered.

Instrumentation Results

The debug plugin confirmed:

[DEBUG] Found new URL(...wasm..., import.meta.url) in SSR env, file: /home/runner/work/astro/astro/triage/issue-15511/src/lib/load-wasm.js
[DEBUG] Environment: ssr, consumer: server

This proves:

1. The new URL('./sample.wasm', import.meta.url) pattern is present in files processed during the SSR build
2. The environment name is ssr with consumer: server
3. Vite's built-in assetImportMetaUrlPlugin skips it because its applyToEnvironment check (consumer === "client") returns false

Root Cause (Confirmed)

File: Vite's internal assetImportMetaUrlPlugin (in vite/src/node/plugins/assetImportMetaUrl.ts)

Lines: In vite@7.1.7 bundled at dep-Bm2ujbhY.js:30226-30228:

applyToEnvironment(environment) {
    return environment.config.consumer === "client";
}

The same restriction exists in vite@6.4.1 (dep-D4NMHUTW.js:41359-41361), confirming this has been the behavior since the Vite Environment API was introduced.

Why this causes the bug:

1. Vite's assetImportMetaUrlPlugin handles new URL('./file', import.meta.url) patterns by:
   • Resolving the file path
   • Emitting the file as a hashed asset via Rollup's this.emitFile()
   • Rewriting the URL to point to the emitted asset (e.g., /_astro/sample.ABC123.wasm)
2. But this plugin only runs for consumer === "client" environments
3. In the Cloudflare adapter's SSR build (consumer: "server", name: "ssr"), the plugin is skipped entirely
4. The new URL("./sample.wasm", import.meta.url) expression passes through to the output verbatim
5. The .wasm file is never emitted anywhere in dist/
6. At runtime on Cloudflare Workers, import.meta.url doesn't resolve to a filesystem path, and the file doesn't exist — causing a crash

Why this is NOT a Vite bug:
Vite intentionally skips this transform for SSR because Node.js servers have filesystem access, so import.meta.url resolves correctly to local file paths at runtime. The issue is that Cloudflare Workers are a serverless/edge runtime with no filesystem — a gap the Cloudflare adapter needs to bridge.

Affected Files

• Vite internal (not to be modified): assetImportMetaUrlPlugin at vite/src/node/plugins/assetImportMetaUrl.ts
• Cloudflare adapter (to be modified): packages/integrations/cloudflare/src/index.ts
• New plugin needed: packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts

Suggested Fix Approach

Create a new Vite plugin in the Cloudflare adapter that replicates assetImportMetaUrlPlugin behavior for the ssr environment:

1. Apply to SSR only: applyToEnvironment: (env) => env.name === 'ssr'
2. Detect patterns: Use the same regex as Vite: /\bnew\s+URL\s*\(\s*('[^']+'|"[^"]+"|[^]+)\s*,\simport.meta.url\s(?:,\s*)?)/dg`
3. Emit assets: Read the referenced file from disk and emit via this.emitFile({ type: 'asset', name, source })
4. Rewrite URLs: Replace the new URL(...) expression with a URL pointing to the emitted asset path (e.g., new URL("/_astro/sample.ABC123.wasm", import.meta.url))

The pattern should handle at minimum .wasm files, but could also handle other binary assets that follow the same new URL() pattern (images, fonts, etc.) to be future-proof.

Edge Cases to Consider

• Template literal URLs with dynamic segments (e.g., new URL(`./dir/${name}.wasm`, import.meta.url))
• Files in public/ directory (should use public path, not emit)
• Multiple references to the same file (should emit once, reuse reference)
• Non-WASM file types that use the same pattern

Confidence

High — The root cause is confirmed via direct instrumentation. The applyToEnvironment restriction in Vite is clearly visible in the source code for both Vite 6 and 7, and the debug output proves the SSR transform sees the WASM file but has no plugin to handle it. The previous triage's diagnosis was correct.

Fix

Status: FIXED

What was changed and why

Added a new Vite plugin (@astrojs/cloudflare:wasm-url) to the Cloudflare adapter that replicates Vite's built-in assetImportMetaUrlPlugin behavior for the SSR environment. This bridges the gap between Vite's intentional SSR behavior (which assumes filesystem access) and Cloudflare Workers' constraint of having no filesystem.

New file: packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts

• A Vite plugin that applies only to the ssr environment (applyToEnvironment: (env) => env.name === 'ssr')
• Uses the same regex as Vite's assetImportMetaUrlPlugin to detect new URL('./file.wasm', import.meta.url) patterns
• Reads the referenced file from disk and emits it via Rollup's this.emitFile() as a hashed asset
• Rewrites the URL to use Vite's __VITE_ASSET__<referenceId>__ placeholder, which Vite's existing vite:asset plugin resolves in renderChunk to the correct asset path
• Currently handles .wasm files (the most common use case), with the ASSET_EXTENSIONS set easily extensible for other binary asset types
• Skips template literals with dynamic expressions, data URLs, absolute URLs, and virtual modules

Modified file: packages/integrations/cloudflare/src/index.ts

• Added import { createWasmUrlPlugin } from './vite-plugin-wasm-url.js'
• Added createWasmUrlPlugin() to the Vite plugins array

Full git diff

diff --git a/packages/integrations/cloudflare/src/index.ts b/packages/integrations/cloudflare/src/index.ts
index 412b4a5..742ae1e 100644
--- a/packages/integrations/cloudflare/src/index.ts
+++ b/packages/integrations/cloudflare/src/index.ts
@@ -9,6 +9,7 @@ import { astroFrontmatterScanPlugin } from './esbuild-plugin-astro-frontmatter.j
 import { createRoutesFile, getParts } from './utils/generate-routes-json.js';
 import { type ImageService, setImageConfig } from './utils/image-config.js';
 import { createConfigPlugin } from './vite-plugin-config.js';
+import { createWasmUrlPlugin } from './vite-plugin-wasm-url.js';
 import {
 	cloudflareConfigCustomizer,
 	DEFAULT_SESSION_KV_BINDING_NAME,
@@ -217,6 +218,7 @@ export default function createIntegration(args?: Options): AstroIntegration {
 							createConfigPlugin({
 								sessionKVBindingName,
 							}),
+							createWasmUrlPlugin(),
 						],
 					},
 					image: setImageConfig(args?.imageService ?? 'compile', config.image, command, logger),

diff --git a/packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts b/packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts
new file mode 100644
--- /dev/null
+++ b/packages/integrations/cloudflare/src/vite-plugin-wasm-url.ts
@@ -0,0 +1,115 @@
+import { readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import type { Plugin } from 'vite';
+
+const assetImportMetaUrlRE =
+	/\bnew\s+URL\s*\(\s*('[^']+'|"[^"]+"|`[^`]+`)\s*,\s*import\.meta\.url\s*(?:,\s*)?\)/dg;
+
+const ASSET_EXTENSIONS = new Set(['.wasm']);
+
+function isAssetFile(url: string): boolean {
+	const ext = path.extname(url.split('?')[0]);
+	return ASSET_EXTENSIONS.has(ext);
+}
+
+export function createWasmUrlPlugin(): Plugin {
+	return {
+		name: '@astrojs/cloudflare:wasm-url',
+		applyToEnvironment(environment) {
+			return environment.name === 'ssr';
+		},
+		transform: {
+			filter: { code: /new\s+URL.+import\.meta\.url/s },
+			async handler(code, id) {
+				if (id.startsWith('\0')) return;
+				const replacements: { start: number; end: number; replacement: string }[] = [];
+				let match: RegExpExecArray | null;
+				assetImportMetaUrlRE.lastIndex = 0;
+				while ((match = assetImportMetaUrlRE.exec(code)) !== null) {
+					const indices = match.indices!;
+					const [startIndex, endIndex] = indices[0];
+					const [urlStart, urlEnd] = indices[1];
+					const rawUrl = code.slice(urlStart, urlEnd);
+					if (rawUrl[0] === '`' && rawUrl.includes('${')) continue;
+					const url = rawUrl.slice(1, -1);
+					if (!isAssetFile(url)) continue;
+					if (url.startsWith('data:') || url.startsWith('http:') || url.startsWith('https:')) continue;
+					let file: string;
+					if (url[0] === '.') {
+						file = path.resolve(path.dirname(id), url);
+					} else { continue; }
+					let source: Buffer;
+					try { source = readFileSync(file); }
+					catch { continue; }
+					const referenceId = this.emitFile({
+						type: 'asset', name: path.basename(file),
+						originalFileName: path.relative(this.environment.config.root, file),
+						source,
+					});
+					const builtUrl = `__VITE_ASSET__${referenceId}__`;
+					replacements.push({
+						start: startIndex, end: endIndex,
+						replacement: `new URL(${JSON.stringify(builtUrl)}, import.meta.url)`,
+					});
+				}
+				if (replacements.length === 0) return;
+				let result = code;
+				for (let i = replacements.length - 1; i >= 0; i--) {
+					const { start, end, replacement } = replacements[i];
+					result = result.slice(0, start) + replacement + result.slice(end);
+				}
+				return { code: result, map: null };
+			},
+		},
+	};
+}

Verification Results

Before fix:

• dist/ contained NO .wasm files
• Worker code contained verbatim: new URL("./sample.wasm", import.meta.url)

After fix:

• WASM file emitted at: dist/client/_astro/sample.DkMAU0Nf.wasm
• Worker code rewritten to: new URL("/_astro/sample.DkMAU0Nf.wasm", import.meta.url)
• Asset path /_astro/sample.DkMAU0Nf.wasm is registered in the build manifest's assets array
• Astro's "Rearranging server assets" build step automatically places the emitted asset in dist/client/ where Cloudflare serves static assets

Regression Testing

All 151 existing Cloudflare adapter tests pass with 0 failures:

• astro-dev-platform, astro:env, BindingImageService, CompileImageService, Custom entry file, ExternalImageService, Routing priority, Server entry, SQL Import, SSR dependencies, Static output, SolidJS, Svelte, Vue, WranglerPreviewPlatform, cloudflareConfigCustomizer, Prerendered page styles, _routes.json generation, sessions, sessions with custom binding name

Alternative Approaches Considered

1. Modifying Vite's assetImportMetaUrlPlugin directly: Rejected because the consumer === "client" restriction is intentional — Node.js SSR environments correctly use filesystem access for import.meta.url resolution.

2. Using generateBundle/writeBundle hooks to copy assets to client dir: Initially implemented but removed after discovering Astro's build pipeline already handles this via its "Rearranging server assets" step. The simplified plugin is cleaner.

3. Handling all file types (not just .wasm): Kept the ASSET_EXTENSIONS set limited to .wasm for now to minimize blast radius. The set is easily extensible if other binary asset types need the same treatment in the future.

This report was made by an LLM. Mistakes happen, check important info.