FOUC in SPA on (re)load.

[Leftium]

Describe the bug

There is a jarring style transition if:

• Kit in SPA mode.
• Root +template loads CSS file.

Reproduction

1. (Re)load https://spa-fouc-no-pico--kit-demos.netlify.app/ in (mobile browser)
2. Notice header starts black and flashes to red color.
3. Repo: https://github.com/Leftium/kit-demos/tree/spa-fouc-no-pico

System Info

• iPhone 13 mini with iOS 18.1.1
• mobile Safari

System:
    OS: Windows 11 10.0.22631
    CPU: (8) x64 Intel(R) Core(TM) i5-8250U CPU @ 1.60GHz
    Memory: 11.28 GB / 23.86 GB
  Binaries:
    Node: 22.12.0 - V:\scoop\apps\nodejs-lts\current\node.EXE
    npm: 10.9.0 - V:\scoop\apps\nodejs-lts\current\npm.CMD
    pnpm: 9.13.2 - V:\pnpm-home\pnpm.CMD
  Browsers:
    Edge: Chromium (127.0.2651.74)
    Internet Explorer: 11.0.22621.3527
  npmPackages:
    @sveltejs/adapter-static: ^3.0.6 => 3.0.8
    @sveltejs/kit: ^2.0.0 => 2.15.2
    @sveltejs/vite-plugin-svelte: ^4.0.0 => 4.0.4
    svelte: ^5.0.0 => 5.17.3
    vite: ^5.4.11 => 5.4.11

Severity

annoyance

Additional Information

• I started investigating this due to FOUC of white background when (system-prefers) dark mode.

  • The flash of white background can be prevented if global CSS is inlined directly into the app.html page template.

• Related issue: Global styles or scripts #3127 (comment)

• I simplified this issue to the absolute minimal reproduction, but it might be worth looking at the original issue I wrote involving PicoCSS:

Original issue with more details, including how to consistently reproduce on desktop.

Describe the bug

There is a jarring style transition if:

• Kit in SPA mode.
• Root +template loads CSS file.
• The CSS file loads PicoCSS.
• edit: PicoCSS is not required, but makes the FOUC more apparent.

Reproduction

Plain CSS without PicoCSS:

• https://spa-fouc-no-pico--kit-demos.netlify.app/
• https://github.com/Leftium/kit-demos/tree/spa-fouc-no-pico

With PicoCSS:

• https://spa-fouc--kit-demos.netlify.app/
• https://github.com/Leftium/kit-demos/tree/spa-fouc

Although visible on desktop, the FOUC is most visible on mobile (iOS Safari).

• Just reload the page to see header flashing from black to red color.
• The FOUC seems less visible when served locally (pnpm preview).

To make FOUC easier to see on desktop adjust dev tools (and ensure serving from pnpm preview):

• Disable cache
• Throttle network to 3G

Additional Information

• If PicoCSS is moved from app.css to app.html the FOUC stops occurring is much more subtle and less pronounced:

  • https://spa-fouc-load-pico-in-app-html--kit-demos.netlify.app/
  • https://github.com/Leftium/kit-demos/tree/spa-fouc-load-pico-in-app-html
  • While this seems like a work-around, it makes it difficult to configure PicoSS via SASS. edit: no longer complete work-around.
  • It is much more difficult to see on desktop, but is clearly evident when reloading on mobile (iOS Safari.) Only the h1 color flashes to red. (I also witnessed this once on desktop.)

• If PicoCSS is loaded in both app.css and app.html there is a limited FOUC:

  • Only the h1 color (set in app.css) flashes black to red.
  • The PicoCSS-related styles are already set and do not flash.

• If PicoCSS is not loaded at all, there does not seem to be a FOUC. the FOUC is only noticeable on mobile.

• This FOUC seems more pronounced on mobile (iOS Safari), even without network throttling. Usually quite visible on each page reload.

[Leftium]

Upon further investigation, PicoCSS is not needed to reproduce. However PicoCSS causes the FOUC to be much more noticeable.

• I don't think there is anything special in the PicoCSS styles. (I initially suspected CSS transitions.)
• My guess is the additional CSS added by PicoCSS causes a longer delay before the FOUC goes away.

[teemingc]

Closing this as I can't seem to reproduce the issue on Chrome desktop or Safari mobile.

[Leftium]

@eltigerchino: Is there anything I can do to help you reproduce the bug?

Here is a short video of the FOUC in Chrome desktop: https://github.com/user-attachments/assets/01da66d2-fe89-45f7-89e8-4876ebc80659

• Did you load https://spa-fouc--kit-demos.netlify.app? (the version without PicoCSS is harder to reproduce on desktop.)
• https://github.com/Leftium/kit-demos/tree/spa-fouc
• Did you disable cache?
• Did you set network throttling to 3G?

Here is a short video of the FOUC in Safari: https://github.com/user-attachments/assets/9f320682-94be-45d1-9618-ddfbdde75add

• This reproduces without PicoCSS (just minimal SvelteKit template project)
• https://spa-fouc-no-pico--kit-demos.netlify.app/
• https://github.com/Leftium/kit-demos/tree/spa-fouc-no-pico

[Leftium]

I have confirmed inlining the styles into the app.html page template fixes the FOUC.

• I think linking to a CSS file also works, if it is one of the first items in the <head>.

So it would be nice to have a way to inline global CSS (and SASS) into app.html.

• This related issue was closed with the argument global scripts and CSS could be loaded in the root +layout: Global styles or scripts #3127 (comment)
• However, I think this issue shows the root +layout is not always sufficient.
• The simplest case is a project with CSS for darkmode. There will always be a chance for a flash of white background unless the darkmode CSS is inlined directly into the app.html file.

[Leftium]

Potential work-around:

• If an SPA project has the freedom to set ssr=true without a fallback page
• The link to the CSS is inlined into the index.html.
• I believe this eliminates the FOUC.

[thnee]

AFAIK, this is how it works now:
On initial page load, the client receives the fallback page.
The fallback page only contains what is statically coded into the app.html source file.
Everything else is rendered by javascript at runtime, aka CSR, including the root +layout and everything below it.
So, the main CSS file in the project, that is typically included like import "$lib/styles/main.css"; in the root layout, is also not present at initial page load.

So for example:
If there is no additional static CSS in app.html, there is a flash of unstyled content on the page. This includes a white flash of the background for dark mode users, which is very jarring.
If there is no static title in app.html, there is a flash of no title in the browser tab.

Personally, when I look at the general support for the various rendering modes via the ssr and prerender flags, and I look at the content of the default app.html, I guess it gives me the impression that SvelteKit would render the values from <svelte:head> and the imported css file in the root layout, into the fallback page, or something like that.

This isn't a major problem or limitation in SvelteKit. Once you understand what is happening, it can be solved correctly.
And I know SPA/CSR can be a confusing topic, and I should now better as a developer.
But I think there is some room for additional handholding from SvelteKit in this case.

It would be a good start if the Single-page apps docs would clearly explain that by default, FOUC will happen, and why it happens, and examples of how to solve it.

Side note: The docs for mode-watcher claims to achieve no FOUC even with CSR. Perhaps I am misunderstanding, but AFAIK this seems to not be correct in practice. The reason I bring this up is just to illustrate that the overall experience is confusing.

My current solution

Added this to <head> in app.html:

<title>My title</title>
<link rel="stylesheet" href="%sveltekit.assets%/style.css" />

Added this in static/style.css:

@media (prefers-color-scheme: dark) {
	:root {
		background-color: var(--root-bg, var(--color-base-100, #222));
	}
}

I'm using tailwind and daisyUI, so that's what the variables refer to.
But notice the additional fallback value of #222 that I added at the end.
Also notice that I am now copying and duplicating the code for background-color.