[Start] Generated route preloads should default to fetchPriority="low" (they delay first paint at High) #8546
Send to my agentWhich project does this relate to?#
Start
Describe the bug#
Start emits every generated route preload (manifest.routes[id].preloads, rendered by HeadContent through getScriptPreloadAttrs) as a plain <link rel="modulepreload">. Chrome fetches those at High priority, so on SSR pages they share bandwidth with the stylesheet, font and LCP image, and they delay first paint even though the server-rendered page needs none of that JS to paint.
I think fetchPriority="low" should be the default for these preloads. React already sets fetchPriority: 'low' on the preloads for its own bootstrapScripts/bootstrapModules, and Next.js inherits that, so SSR pages built on either load their startup JS behind render-critical resources by default. Start is the outlier. There's also no supported way to change it: HeadContent accepts assetCrossOrigin and transformAssets can rewrite the URL and crossOrigin, but neither can set priority.
Draft PR #8212 implements the default. It has had no maintainer review since it was opened on Sept 2.
Production before/after on webcatalog.io (Start 1.168, React 19.3, Vite 8; 71–79 preloads per page, about 445 KB of JS). The only change was fetchpriority="low" on the generated preloads. Lighthouse 13.5 medians (3 runs before, 5 after):
| Page | Form | Perf | FCP | Speed Index |
|---|---|---|---|---|
| /en/desktop | mobile | 47 → 66 | 6.9 s → 3.5 s | 6.9 s → 4.2 s |
| /en/desktop | desktop | 71 → 90 | 2.6 s → 674 ms | 2.6 s → 951 ms |
| /en/apps/ometv | mobile | 35 → 67 | 6.8 s → 3.5 s | 6.8 s → 4.2 s |
| /en/apps/ometv | desktop | 66 → 83 | 2.6 s → 641 ms | 2.7 s → 1.0 s |
| /en/apps/country/us | mobile | 59 → 65 | 6.4 s → 3.5 s | 6.4 s → 5.1 s |
| /en/apps/country/us | desktop | 80 → 80 | 1.3 s → 633 ms | 1.3 s → 924 ms |
A second production site, lexibird.com (same stack, 43 preloads), with the same change, 5 runs each:
| Page | Form | Perf | FCP | Speed Index |
|---|---|---|---|---|
| /en/desktop | mobile | 61 → 67 | 5.5 s → 3.1 s | 5.5 s → 4.7 s |
| /en/desktop | desktop | 84 → 93 | 1.7 s → 817 ms | 1.7 s → 929 ms |
TBT, TTI and hydration are unchanged within noise on both sites, and neither site showed hydration errors in production.
Real-user cost, measured under applied throttling (real Chrome, Lighthouse devtools settings, 5 interleaved runs; methodology in https://github.com/TanStack/router/pull/8212#issuecomment-5871175691):
default (High) | fetchpriority="low" | |
|---|---|---|
| Mobile FCP (= LCP) | 4.44 s | 2.87 s |
Mobile hydrated ($_TSR.h()) | 6.71 s | 6.58 s |
| Mobile first successful menu click | 7.23 s | 7.03 s |
| Mobile slowest click (Event Timing) | 96 ms | 112 ms |
| Desktop FCP | 660 ms | 388 ms |
| Desktop hydrated | 917 ms | 933 ms |
Hydration doesn't move. The connection is the bottleneck, so the last chunk arrives at the same time either way; low only lets render-critical resources go first. With production verified on mobile and desktop Chrome, hydration, menus and client-side navigation all work unchanged.
Why a default rather than an opt-in:
- When it helps, it helps a lot (above), and every SSR Start app pays the cost today without knowing it.
- When it doesn't help, it's harmless. With a small preload set the difference under real throttling is close to zero either way (PR #8212's description, and @TiagoGranelli's measurements there). No measured case gets slower for SSR-rendered content.
- It matches the platform consensus: React's bootstrap preloads, Next.js, and Chrome's own Fetch Priority guidance for non-critical preloaded scripts.
- Hardly anyone will opt in. The cost doesn't show up in the code, only in field metrics, so an opt-in would be discovered by the few teams who go looking for it.
Where the default should not apply, and one case we measured:
ssr: falsematches and SPA mode. There the JS is the content, so it should keep today's priority. Start knows at render time which matches were server-rendered, so the default can be scoped to those.- Pages whose LCP element is rendered on the client after hydration. On
/en/apps/country/us(desktop), the LCP element is a client-fetched card, and Lighthouse's simulated LCP went from 2.9 s to 3.6 s (consistent across runs) even though observed LCP improved (1.49 s → 1.36 s). That's the same class asssr: false: content that waits on JS. It's a reason for an escape hatch, not for leaving the default alone.
Complete minimal reproducer#
https://stackblitz.com/github/tanstack/router/tree/main/examples/react/start-basic
Steps to Reproduce the Bug#
- Open the
start-basicexample and load any page. - View the page source: each generated preload is
<link rel="modulepreload" href="/assets/…">with nofetchPriority. - In DevTools → Network (with the Priority column on), these requests are
High, starting alongside the stylesheet. - Compare with a Next.js page, where the bootstrap script preloads are
fetchpriority="low".
To see the FCP cost, the preload set has to be large relative to the render-critical bytes, as in the app measured above (dozens of chunks, hundreds of KB).
Expected behavior#
As an app author, I expected Start to treat generated preloads as non-render-blocking, the way React and Next.js treat their bootstrap preloads. Instead they're fetched at High and compete with the stylesheet, font and LCP image.
Proposed:
getScriptPreloadAttrsemitsfetchPriority: 'low'by default for preloads of server-rendered matches (what #8212 does, scoped to excludessr: falsematches and the SPA shell).- An escape hatch for apps that need the old behavior, e.g.
fetchPriorityonTransformAssetResultor aHeadContentprop next toassetCrossOrigin. - Static Early Hints forward
fetchPriority.early-hints.tscurrently copies onlyhref,rel,asandcrossOrigin, so wherever a browser acts on the hint, the HTML attribute arrives too late to matter (point 4 in #8212).
For the escape hatch, React 19.3 already exposes the same knob per call: ReactDOM.preloadModule() forwards fetchPriority (react/react#36835).
Screenshots or Videos#
No response
Platform#
- Router / Start Version: @tanstack/react-start 1.168.58, @tanstack/react-router 1.170.39, @tanstack/router-core 1.171.32
- OS: macOS
- Browser: Chrome
- Browser Version: 154
- Bundler: vite
- Bundler Version: 8.3.1
Additional context#
Related: #8212 (draft PR implementing the default), discussion #8547, #6749 (stylesheet vs modulepreload ordering), #8511 (preload waterfall with Rolldown).
Current workaround: since useTags and Asset are exported, an app can replace HeadContent with its own version that adds fetchPriority: 'low' to link[rel=modulepreload] tags. That's what produced the production numbers above, but it re-implements HeadContent and doesn't reach Early Hints.
Edited 2026-09-28: added lexibird.com as a second production site; updated with production before/after data, and changed the ask from an opt-in to a default (scoped to server-rendered matches) with an escape hatch.
quanglam2807(GitHub profile, opens in a new tab) changed the title
Sign in to join this conversation.
Another data point, from a Start 1.168 SSR app (React 19, Vite 8). Our home page emitted 51 route preloads, about 480 KB of JS. We tried the other approach: removing the preloads entirely. We did it with a small Vite plugin that deletes
routes[*].preloadsfrom thetanstack-start-manifest:vmodule in thessrbuild, so the server<head>and the manifest sent to the client for hydration still match.The cause looks the same as yours. On a Lighthouse devtools-throttled run of the production site (mobile, real network throttling), the HTML arrived at 1.24 s. The 35 KB stylesheet was requested at the same moment as the 51 preloads, all at High priority, and didn't finish until 3.5 s. FCP and LCP were both 3.3–3.9 s, with the LCP element being SSR text.
Before and after, the same SSR build served locally behind an HTTP/2 + gzip proxy, Lighthouse 13.5 mobile, devtools throttling, 3 runs each:
The waterfall that #7197 warns about did show up. The browser finds the chunks by parsing the entry. At this bundle size it didn't show in TTI. We'd still rather use
fetchPriority="low"from #8212 than a manifest transform that depends on the virtual module's shape, so a supported option (the default proposed here, or atransformAssetsresult that can drop a preload or set its priority) would let us delete the plugin.