Astro 5 upgrade causing unstyled content flash when using ClientRouter | Astro Lounge | Page 1

stuck lintel Sep 4, 2025, 10:09 PM

#

We've been running our documentation with Astro for a few years now. We upgraded to NodeJS 22 a few weeks ago, and we noticed a flash of unstyled content between page transitions using the <ClientRouter />. When I start the dev server, the issue isn't present, but I've managed to reproduce the issue locally by switching from the Vercel adapter to the NodeJS one and running astro preview on a local build. I'm testing on Chromium (Arc). In order to troubleshoot the issue.

Changes that may have something to do with it:

Upgraded NodeJS from 18 to 22
Upgraded astro from 4.11 to 5.12
Change scss additionalData: '@import "./src/styles/variables.scss";' to additionalData: '@use "./src/styles/variables.scss" as *;'
Changed from mode: hybrid to mode: static

I've tried:

Removing any code related to theme control (dark/light mode)
Settingtransition:animate="none" on the root
Upgrading Astro to 5.13.5
Nuking node modules & yarn.lock and reinstalling dependencies

I haven't been able to isolate those changes since they are all interdependent and can't get the build working without them. I'm stuck, which is why I'm posting here. Any hint?

stuck lintel Sep 4, 2025, 11:59 PM

#

Update: I've been able to eliminate the SCSS import change as a potential root cause by using a previous Node 18 build, upgrading to Node 20, and changing only that one line.

Change scss additionalData: '@import "./src/styles/variables.scss";' to additionalData: '@use "./src/styles/variables.scss" as *;'

stuck lintel Sep 5, 2025, 12:34 AM

#

Astro 5 upgrade causing unstyled content flash when using ClientRouter

#

I've also validated that the node version itself is not the culprit. Seemingly, the astro upgrade from 4 to 5 is causing this issue. Downgrading is a nightmare since we've added a lot of new pages and content since, and there's a ton of build errors on 4 now.

heady crane Sep 5, 2025, 4:16 PM

#

Hi @stuck lintel 👋, can you give me access to a deployment of the new site so i could take a look at, and to the old site for comparison?

stuck lintel Sep 5, 2025, 8:57 PM

#

@heady crane What's your github handle?

#

Nvm, grabbed it from you profile 🙂

heady crane Sep 6, 2025, 5:38 PM

#

cloned it, added ClientRouter (ViewTransitions) back to end of <head> in DocsLayout.astro, ran it locally, can't reproduce the video above.

#

I'm using Chrome 140, Astro is running on Node v22.9.0 Linux (Windows WSL2)
There is a similar issue on withastro/astro (https://github.com/withastro/astro/issues/14316) also vercel adapter, which I, too, can not reproduce.
They are on MacOs
Do you have any suggestions how to reproduce the bug more reliably? (tried network throttling with disabled caches, without success)

stuck lintel Sep 6, 2025, 6:44 PM

#

@heady crane Did you try reproducing with the dev server or a proper build & astro preview?

heady crane Sep 6, 2025, 6:46 PM

#

the video is from the dev server.

stuck lintel Sep 6, 2025, 6:46 PM

#

That linked issue does look extremely similar.

heady crane Sep 6, 2025, 6:46 PM

#

Astro preview failed with errors for me.

stuck lintel Sep 6, 2025, 6:46 PM

#

The dev server doesn't exhibit the issue, the video was from astro preview swapping to the nodejs adapter for the purpose of running locally

#

Which has made trying to debug this particularly painful 🙈

#

Let me try to get back to a state where I can both run and reproduce locally and open a PR with it

cerulean wigeon Sep 6, 2025, 6:48 PM

#

Potentially related, I think I remember the Starlight team having issues with FOUCs recently. Does this only happen with the ClientRouter?

stuck lintel Sep 6, 2025, 6:48 PM

#

Yeah only happens with ClientRouter on 5.X

cerulean wigeon Sep 6, 2025, 6:49 PM

#

Alright. Nevermind that then kek

heady crane Sep 6, 2025, 6:49 PM

#

Hi Lou!

stuck lintel Sep 6, 2025, 6:49 PM

#

Possibly related to the Vercel adapter upgrade from 6.x to 8.x unclear since they can't be tested in isolation

heady crane Sep 6, 2025, 6:51 PM

#

I'll try preview with the node adapter...

#

good news, I can reproduce it when throttling.

stuck lintel Sep 6, 2025, 7:07 PM

#

That's a step! With the dev server or preview?

heady crane Sep 6, 2025, 7:08 PM

#

preview with the node adapter, so it has definitively nothing to do with the vercel adapter 😉

stuck lintel Sep 6, 2025, 7:09 PM

#

I was definitely able to reliably reproduce it without throttle as well. Just put the kid to sleep, s trying again now. I've tried so many different things to isolate that I might have gotten mixed up

heady crane Sep 6, 2025, 7:10 PM

#

🙂

#

i have enough to investigate right now. looks like the page shows unstyled before the view transition even starts. Strange.

stuck lintel Sep 6, 2025, 7:12 PM

#

Glad to hear I'm getting some help here 🙌

heady crane Sep 6, 2025, 7:13 PM

#

not promised, but working on it 😉

#

stuck lintel Sep 6, 2025, 7:15 PM

#

Just pushed chore/reproduction-fouc which has the minimum changes I need to do to repro locally. Likely the same thing you are working with but just in case.

heady crane Sep 6, 2025, 7:16 PM

#

this definitively looks like the issue i mentioned.

stuck lintel Sep 6, 2025, 7:16 PM

#

Right so possibly less of an edge case then it looks if there's multiple reports

heady crane Sep 6, 2025, 7:16 PM

#

lucky to have yours as a repro when the other was not reproducible for ne 😉

#

looks like some unexpected "optimization"

stuck lintel Sep 6, 2025, 7:18 PM

#

I'm not familiar enough with astro under the hood to speculate 😅

#

Given it's not an issue with the dev server though I'd imagine the difference between the 2 to really just boil down to optimizations

heady crane Sep 6, 2025, 10:24 PM

#

The root cause of the broken styling is the miss-placement of the <SpeedInsights/> component.
It's placed inside the head, where it inserts a custom-tag. The browser knows, that those do not belong in the head. So it closes the head and starts the body. Everything that follows the custom-tag is now also in the body, including styling that should have been in the head.
In the HTML, everything looks fine. but if you examine the DOM in Devtools, you will see, that for example your og:* properties end up in the body. This also happens with your current production site.
Long story short: When the <ClientRouter /> (new name for <ViewTransitions />) swaps the body, styles are cleared and than reloaded which leads to the FOUC.
For my tests, moving <SpeedInsights /> from <Headers> to the <body> (in DocsLayout) did the trick. Let me hear if that's a reproducible solution on your end, too.

stuck lintel Sep 7, 2025, 12:11 AM

#

🤯 Wow thank you so much, never in a million years would I have considered that.

#

Will try in the morning!

heady crane Sep 8, 2025, 5:47 PM

#

@stuck lintel any progress?

stuck lintel Sep 9, 2025, 7:23 PM

#

@heady crane Left camping for a few days, giving it a burn tonight!

heady crane Sep 9, 2025, 7:35 PM

#

Haha, no rush on my end, but if that did the trick, we can just close the thread after.

brisk spindleBOT Sep 9, 2025, 7:35 PM

#

If your issue is resolved, please help by doing the following two steps:

From the ellipses (3-dot menu) in the top-right corner of the post (not the first message), edit the tags to include the Solved tag.
From the same ellipses, select Close Post.
Your post will still be available to search and can be re-opened simply by replying in it. Closing a post moves it down with older posts, so we can more easily focus on issues that still need to be resolved.
Thank you for your help!

#Astro 5 upgrade causing unstyled content flash when using ClientRouter