`<head>` element ordering: `link[stylesheet]` should come before `link[modulepreload]` #6749
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
In headContentUtils.tsx, preloadLinks are placed before links, which means <link rel="modulepreload"> elements appear before <link rel="stylesheet"> in the rendered <head>.
Browsers fetch resources top-to-bottom. When modulepreload links come first, the render-blocking CSS resources needed to display styled SSR HTML get discovered late. Under HTTP/1.1's 6-connection-per-host limit, the CSS request can't even start until earlier JS downloads free up a connection.
Key result (Using a slow 4G throttle + 22 slow modulepreload links):
| Scenario | FCP | Δ |
|---|---|---|
| HTTP/1.1 — modulepreload first | 2075ms | |
| HTTP/1.1 — stylesheet first | 1260ms | −815ms (39%) |
| HTTP/2 — modulepreload first | 1388ms | |
| HTTP/2 — stylesheet first | 1380ms | −8ms (~1%) |
ℹ️ Happy to open a PR if this is something you'd like to see fixed. 🚀
Your Example Website or App#
https://github.com/steschi/html-head-order-matters
Steps to Reproduce the Bug or Issue#
- Create a TanStack Router SSR app with multiple route chunks (so Vite emits many modulepreload links) as well as a stylesheet import.
- Build and serve with
vite preview(HTTP/1.1) - Open Chrome DevTools → Network tab, throttle to Slow 4G
- Load the page and observe the waterfall: modulepreload fetches start before the stylesheet fetch
- The stylesheet is blocked behind the 6-connection limit, delaying FCP
Expected behavior#
<link rel="stylesheet"> should appear before <link rel="modulepreload"> in the <head>, so the browser discovers and fetches render-blocking CSS first. This matches the capo.js recommended element ordering (stylesheets = weight 5, modulepreload = weight 4).
Screenshots or Videos#
See the full reproduction repo for waterfall charts and Chrome DevTools traces: https://github.com/steschi/html-head-order-matters
Platform#
- Router / Start Version: 1.162.4 with nitro v3
- OS: macOS
- Browser: Chrome
- Browser Version: Chrome 145
Additional context#
- capo.js —
<head>ordering audit tool by Rick Viscomi (Google) - Harry Roberts — "Get Your Head Straight" — talk on
<head>ordering and Core Web Vitals
Hi @steschi and maintainers! This is a great finding and a clear improvement. If no one is working on this yet, I'd love to take this issue and open a PR. Please let me know if I can go ahead!
Hi @jong-kyung, thanks for your feedback! I'd actually love to do the PR myself if the maintainers allow it. I spent quite a bit of time tracking down the issue and building the reproduction, so it would be great to carry it across the finish line, especially since I already looked into how to fix this.
Hi @steschi, I totally agree. Since you've already done the hard work of investigating and reproducing the issue, it’s right that you open the PR. I'll be looking forward to it!
schiller-manuel(GitHub profile, opens in a new tab) added labelsstart-head
Also running in to this issue. Any updates on potential PR?
we'll work on head management fixes/updates soon
This also has the effect that, on navigation, the whole page flashes as modulepreload links are added. The CSS is then invalidated and, for a split second, not applied which makes the whole page reset styles. This only happens in production builds, not in dev.
@Trombecher how is the ordering related to css style reset?
@schiller-manuel no idea, it just seems like it does. Whenever I navigate, it adds modulepreload links to the head and because the css link is below all modulepreload links, it seems like it invalidates the css for a split second.
@Trombecher please provide a complete reproducer project as a git repo
On production, the public site could briefly render as raw unstyled HTML on first load or after opening links . i had to add this for now
<script dangerouslySetInnerHTML={{ __html: `document.write('<link rel="stylesheet" href="${appCss}">')`, }} />On React this reorder may not change the HTML. With
@tanstack/react-router1.170 and React 19.3,Assetrenders manifest stylesheets withprecedence="default", and React hoists those stylesheets ahead of the other head children, so the order frombuildTagsFromMatchesnever reaches the page. Our SSR and prerendered pages come out as<meta charSet="utf-8"/><meta name="viewport" …/> <link rel="stylesheet" href="/assets/index-….css" data-precedence="default"/> <meta property="csp-nonce" …/><title>…</title>… <link rel="modulepreload" href="/assets/index-….js"/> …Solid and Vue don't have that hoisting.
For our mobile Lighthouse numbers the protocol made the difference, as in your table. The same build measured through Caddy gave FCP 1.95 s over plain HTTP/1.1, 2.25 s over HTTPS with HTTP/1.1, and 1.50 s over HTTPS with HTTP/2 (Lighthouse 13.5 simulated mobile, 10 to 15 modulepreloads). Lantern models each parallel HTTP/1.1 request as a new connection with its own handshake and slow start. Over HTTP/2 the stylesheet and the preloads share the document's already open connection. Measuring behind TLS, the way production runs, closed most of the gap for us.
Sign in to join this conversation.
Hi @jong-kyung, thanks for your feedback! I'd actually love to do the PR myself if the maintainers allow it. I spent quite a bit of time tracking down the issue and building the reproduction, so it would be great to carry it across the finish line, especially since I already looked into how to fix this.