Skip to content
Source
Sign inSign up
TanStack/router

`<head>` element ordering: `link[stylesheet]` should come before `link[modulepreload]` #6749

Send to my agent
Opensteschi(GitHub profile, opens in a new tab) opened this issue 10 comments

Which 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):

ScenarioFCPΔ
HTTP/1.1 — modulepreload first2075ms
HTTP/1.1 — stylesheet first1260ms−815ms (39%)
HTTP/2 — modulepreload first1388ms
HTTP/2 — stylesheet first1380ms−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

  1. Create a TanStack Router SSR app with multiple route chunks (so Vite emits many modulepreload links) as well as a stylesheet import.
  2. Build and serve with vite preview (HTTP/1.1)
  3. Open Chrome DevTools → Network tab, throttle to Slow 4G
  4. Load the page and observe the waterfall: modulepreload fetches start before the stylesheet fetch
  5. 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

Inefficient head order Performant head order

Platform

  • Router / Start Version: 1.162.4 with nitro v3
  • OS: macOS
  • Browser: Chrome
  • Browser Version: Chrome 145

Additional context

  1. 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.

  2. 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!

  3. schiller-manuel(GitHub profile, opens in a new tab) added labelsstart-head

  4. Also running in to this issue. Any updates on potential PR?

  5. we'll work on head management fixes/updates soon

  6. 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.

  7. @Trombecher how is the ordering related to css style reset?

  8. @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.

  9. @Trombecher please provide a complete reproducer project as a git repo

  10. 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}">')`,
        }}
      /> 
  11. On React this reorder may not change the HTML. With @tanstack/react-router 1.170 and React 19.3, Asset renders manifest stylesheets with precedence="default", and React hoists those stylesheets ahead of the other head children, so the order from buildTagsFromMatches never 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.