[App Router] Critical layout CSS lacks preload link hints in document head
Open
Nobody has claimed this yet.
Performance
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.4k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 351
Description
Link to the code that reproduces this issue
https://github.com/agentHits/next.js/tree/perf/css-preload-links
To Reproduce
- Create an App Router layout with a global stylesheet.
- Run
next build && next start. - Inspect the
<head>markup in the initial HTML response.
Current vs. Expected behavior
- Current: Critical layout stylesheets are referenced only with
<link rel="stylesheet">. The browser's preload scanner only discovers stylesheets as it encounters them in document order. - Expected: Next.js emits
<link rel="preload" as="style">hints in<head>before stylesheets, enabling the preload scanner to initiate stylesheet downloads concurrently and reducing First Contentful Paint (FCP).
Provide environment information
Operating System:
Platform: darwin
Arch: arm64
Version: Darwin Kernel Version 24.2.0
Binaries:
Node: 24.21.0
pnpm: 10.33.0
Relevant Packages:
next: 16.4.0-canary.32
react: 19.3.0
react-dom: 19.3.0
Which area(s) are affected? (Select all that apply)
App Router, Performance
Which stage(s) are affected? (Select all that apply)
next start (production mode)
Additional context
Verified with:
pnpm test-unit packages/next/src/server/app-render/render-css-resource.test.tspnpm test-start-turbo test/e2e/app-dir/css-preload-links/css-preload-links.test.ts
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the reproduction branch and run packages/next/src/server/app-render/render-css-resource.test.ts, then verify test/e2e/app-dir/css-preload-links/css-preload-links.test.ts under next start. Trace App Router production rendering for the initial HTML head. Done means critical layout stylesheets have preload-as-style hints before the stylesheet links and both mentioned tests pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nextjs, react
- Domain
- frontend, performance, web-dev
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100