Bugfix: How to handle @rspack/browser top-level await crash that kil...
Documentation for Sessions
🐛 Bugfix: How to handle @rspack/browser top-level await crash that kil...
Date: 2026-03-11
Time: 23:37:39 UTC
Session: gspace1-205.6
Agent: angular
Confidence: 97%
Status: ✅ Documented
📋 Decision Context
Question:
How to handle @rspack/browser top-level await crash that kills the Angular dev server (esbuild rejects top-level await for browser targets)?
Task: Not specified
🎯 Decision Made
Chosen:
Use variable-based dynamic import:
const modulePath = '@rspack/browser'; await import(/* @vite-ignore */ modulePath)— prevents esbuild from statically resolving the import. Also replacedtypeof import('@rspack/browser')field type withanysince the typeof also forces TypeScript to resolve the module.
Options Considered:
- Raise esbuild target to esnext — breaks compatibility with older browsers
- Variable-based dynamic import — esbuild skips non-literal import specifiers
- Web Worker for rspack — isolates top-level await but adds messaging complexity
- Externalize @rspack/browser in angular.json — would need manual script loading
💭 Reasoning
@rspack/browser's WASI loader (rspack.wasi-browser.js) uses top-level await at lines 30 and 36 to fetch and instantiate the WASM module. esbuild (used by Angular's dev server via @angular-devkit/build-angular) rejects top-level await because the target includes browsers that don't support it (chrome107, ios16). The root cause: even await import('@rspack/browser') is resolved at build time by esbuild. Solution: assign the module path to a variable first — esbuild treats import(variable) as a true runtime-only dynamic import and doesn't try to bundle it. The /* @vite-ignore */ comment prevents Vite warnings. Additionally, typeof import('@rspack/browser') on a field type forces TypeScript to resolve the module at compile time — replaced with any. The Buffer type from the RspackMemFs interface also needed replacing with Uint8Array (browser environment has no Buffer).
📁 Files Involved
libs/libs-structural/platform-preview/src/lib/services/bundler.service.tslibs/libs-structural/platform-preview/src/lib/services/bundler-filesystem.service.ts
🔗 Related
- Decision ID:
dev_1773272259500_04hyakr - Session: 205
- Workspace: gspace1
Auto-generated by MCP Smart Consolidation