# Why SPA Guard? > The problem SPA Guard solves is real, subtle, and nearly universal for any application that ships to production. This page documents the error cases, why standard tools don't cover all of them, and how SPA Guard fills the gaps. # Why SPA Guard? The problem SPA Guard solves is real, subtle, and nearly universal for any application that ships to production. This page documents the error cases, why standard tools don't cover all of them, and how SPA Guard fills the gaps. ## What is a chunk load error? Modern single-page applications use **code splitting**: the JavaScript bundle is divided into smaller files (chunks) that load on demand. When a user navigates to a route, the browser fetches that route's chunk — something like `Home.3f8a2c.js`. The hash in the filename is derived from the chunk's content, so it changes every time the file changes. When you deploy a new version of your app, the old chunk filenames disappear and new ones appear. Any user who had the app open before the deployment still has the old HTML in their browser — with script tags pointing to the old chunk URLs. The moment they navigate to a new route, the browser tries to load a chunk that no longer exists. The server returns a 404. The browser throws: ```text TypeError: Failed to fetch dynamically imported module ``` React's error boundary catches it. The user sees a white screen or an error message. They have no idea why. ## The five error cases Not all chunk-related errors look the same. There are five distinct cases, and each requires a different mechanism to catch. ### Case 1: Chunk load error after deployment (the main case) ```text [User has old tab open] → Deploy v2 (old chunks removed from CDN) → User navigates to lazy route → import('./PageX.abc123.js') → 404 → TypeError: Failed to fetch dynamically imported module → React Router ErrorBoundary may catch (if it's a lazy route) → OR surfaces as unhandledrejection ``` **Solution**: page reload (gets fresh `index.html` → new chunk references). ### Case 2: Error inside a lazily-loaded module ```text [Chunk loaded successfully] → Error thrown during module initialization → React ErrorBoundary catches it → OR surfaces as unhandledrejection ``` **Solution**: React ErrorBoundary + fallback UI. ### Case 3: Main chunk failure before Sentry initializes ```text [index.html received] → Browser requests main.abc123.js → Load fails (network, CDN, ad-blocker) → Sentry NOT initialized (it initializes inside the main chunk) → window.addEventListener('error') NOT registered → Error is completely lost — no one knows it happened ``` This is the critical case. Every other approach assumes the application's JavaScript has already started running. If the main chunk fails, **nothing registered inside that chunk will ever run** — including your error tracker, your event listeners, your Sentry initialization. **Solution**: an inline script embedded directly in `` before all other scripts. This script runs before any chunk is requested, so it's always active regardless of what fails later. ### Case 4: CSS preload failure ```text [Vite loads a CSS chunk] → Resource blocked (network / CDN / ad-blocker) → Two variants: a) DevTools block → browser silently ignores (error event does NOT fire) b) Real 404/network error → 'error' capture phase OR Vite throws: "Unable to preload CSS" → unhandledrejection ``` **Solution**: `window.addEventListener('error', handler, true)` with `capture: true` for HTML element errors; `unhandledrejection` for the Vite-specific preload error. ### Case 5: CSP violation ```text [Browser blocks script by Content-Security-Policy] → Chunk doesn't load → 'securitypolicyviolation' event fires → Standard error/unhandledrejection do NOT fire ``` **Solution**: `window.addEventListener('securitypolicyviolation', handler)`. ## Browser event map Catching all five cases requires four different event listeners. Each covers a different failure mode: | Event | What it catches | Notes | | ------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `window.addEventListener('error', h, true)` | Sync JS errors + resource load failures (`