There are bugs that are difficult.
There are bugs that are interesting.
And then there are bugs that make you stare at your monitor for two weekends and question every architectural decision you've ever made.
This was the third kind.
The problem looked simple enough:
Deploy the frontend.
User has an old tab open.
User does something.
White screen.
Beautiful.
Nothing says "professional software" like clicking a button and getting a blank page because the universe decided your JavaScript file was no longer worthy of existence.
The error
The browser was throwing this:
Failed to fetch dynamically imported module:
https://example.com/assets/Layout-BxXWW-GV.js
Then, because apparently one error wasn't enough:
Failed to load module script:
Expected a JavaScript-or-Wasm module script
but the server responded with a MIME type of "text/html".
At first glance, this looks like a React problem.
It isn't.
It's one of those problems where React is standing nearby holding the bag while Vite and your SPA hosting setup are committing the crime.
What was actually happening
Vite generates hashed JavaScript chunks.
Something like:
Layout-BxXWW-GV.js
When you deploy a new version, Vite generates new files:
Layout-NEW-HASH.js
Meanwhile, somebody has been sitting on the same browser tab since approximately the Stone Age.
Their browser still has the old application loaded.
So eventually the old application says:
Hey, I need
Layout-BxXWW-GV.js.
The new deployment says:
Never heard of her.
That's fine.
A missing asset should return a 404.
But here's where things get stupid.
Because this is an SPA, the hosting configuration has a fallback roughly equivalent to:
Anything you don't recognize?
Sure, here's index.html.So the browser asks for:
/assets/Layout-BxXWW-GV.jsThe server can't find it.
Instead of saying:
404 Not Foundit says:
200 OK
Content-Type: text/htmland hands the browser your index.html.
The browser then looks at it and says:
I specifically asked for JavaScript.
And then everything explodes.
The browser isn't wrong
This part was actually pretty satisfying once I understood it.
The browser is doing exactly what it's supposed to do.
It requested JavaScript.
The server returned HTML.
The browser refused to execute HTML as a JavaScript module.
That's not React being broken.
That's not the browser being annoying.
That's not some mysterious frontend curse.
It's basically this:
Browser:
Give me JavaScript.
Server:
Here is HTML.
Browser:
That's not JavaScript.
Server:
It's the homepage.
Browser:
I don't care.
White screen.
So what is the actual problem?
It's a Vite + SPA hosting/deployment lifecycle problem.
The application has no idea that a newer version has replaced the files it is currently using.
And the hosting layer is incorrectly treating a missing JavaScript asset like a client-side route.
Two completely different things.
A request for:
/dashboard/orders
should probably get:
index.html
because React Router can handle that route.
A request for:
/assets/Layout-OLD-HASH.js
should absolutely not get:
index.html
That is not a route.
That's a missing file.
The fix
I ended up solving this in three pieces.
1. Version detection
Every production build now generates a small:
/version.jsoncontaining the current build information.
Something like:
The running application knows which version it was built from.
It can then compare itself against the currently deployed version.
If you're sitting on an old tab and a new release goes out:
Old tab:
cad1276
Server:
cad1276
Everything is fine.
Then:
Old tab:
cad1276
Server:
deadbeef
Oh.
Now the application can actually tell the user:
New version available. Refresh to get the latest changes.
Which is considerably nicer than:
Congratulations, here's a white screen.
2. Stale chunk recovery
But I didn't want to rely entirely on users seeing the notification.
Because let's be honest.
People don't refresh.
They will keep a browser tab open for six months and then complain that something is broken.
So the app also listens for Vite's preload failure.
If an old lazy-loaded chunk fails:
old chunk
↓
404
↓
vite:preloadError
↓
reload
↓
new index.html
↓
new chunks
↓
hopefully civilization continuesThe reload is capped so we don't accidentally create the world's least impressive infinite reload loop.
First failure:
Okay, let's recover.
Second failure:
Alright, something is genuinely wrong. Stop.
That's important.
Automatic recovery is great.
Automatic infinite suffering is not.
3. Stop pretending assets are routes
The other half of the fix lives in the hosting configuration.
The SPA fallback should still handle application routes.
But missing assets need to remain missing.
Conceptually:
/assets/* → 404
/* → index.htmlSo:
/dashboard/ordersgets the SPA.
But:
/assets/Layout-I-DONT-EXIST.jsgets:
404Not:
200 HTML pretending to be JavaScriptThis also makes the underlying failure honest.
And honestly, I'll take an ugly 404 over a browser being gaslit into thinking an HTML document is a JavaScript module.
The extra nice part
The version detection also means I can now actually tell users that a release happened.
Instead of silently deploying a new frontend and hoping every open browser tab magically figures it out, the application can say:
New version available.
Then the user can refresh when they're ready.
It's a tiny feature, but it changes the deployment experience considerably.
What this taught me
The annoying part is that this isn't some exotic distributed systems problem.
It's a very normal frontend deployment edge case.
But it's also exactly the kind of thing you can accidentally normalize.
You see it once.
Then again.
Then someone says:
Just refresh.
Then everyone collectively decides that's apparently a feature.
And eventually you realize you've spent enough time explaining how to Ctrl+R that you should probably just fix the damn thing.
Which brings me to the slightly embarrassing part.
I had already encountered this kind of problem at my old company.
Apparently I learned to live with it instead of fully understanding why it was happening.
So I spent two Saturdays fixing something I had apparently accepted as part of frontend life.
Character development.
Expensive character development.
The final architecture
The solution is now basically:
New deployment
|
v
New Vite build
|
+--------+--------+
| |
v v
version.json hashed assets
|
v
Existing tab
|
v
detects new version
|
v
"New version available"
|
v
Refresh
And for the nasty case:
Old tab
|
v
Requests old chunk
|
v
Asset no longer exists
|
v
404
|
v
Vite preload error
|
v
One automatic recovery
|
v
Fresh application
No React magic.
No backend API required.
No polling circus.
Just proper version awareness, proper stale-chunk recovery, and proper asset routing.
And finally...
I'm not even mad anymore.
Okay, that's a lie.
I'm still a little mad.
But it's the good kind of mad.
The kind where you finally understand the bug well enough that you can delete the workaround you mentally accepted three years ago.
Two Saturdays later, my portfolio can now survive a frontend deployment without turning into a blank white rectangle.
Was it worth it?
Ask me next Saturday.
EDIT: 33 Hours Later: God Damn It, I Didn't Make It to Next Saturday
Update — 33 hours after deployment
God damn it.
I didn't make it to next Saturday.
The good news?
Everything actually worked.
The version detection did exactly what it was supposed to do. The old tab detected the new deployment and showed the refresh prompt.
I clicked it.
And then:
White screen.
So apparently the bug wasn't finished with me.
The first fix made the failure more honest: instead of the browser receiving index.html disguised as JavaScript, the missing asset finally returned a proper 404.
Progress.
Then that exposed another problem: the global 404.html was interfering with legitimate SPA routes like /analytics/dashboard.
So I fixed that too.
The final routing became:
/assets/missing-file.js
↓
404
/analytics/dashboard
↓
index.html
↓
React Router
↓
Dashboard
After the second deployment:
Version prompt? ✅
Refresh? ✅
Dashboard? ✅
Deep links? ✅
Missing assets return 404? ✅
White screen? ❌
MIME-type nonsense? ❌
Wala. All good in the hood.
So yes, I am officially closing this chapter.
At least until something fucks me up again.
Which, considering I wrote that sentence yesterday...
Apparently I should never make promises about next Saturday.