Skip to content

perf(next-plugin): share what the root layout imports across every route - #1037

Open
owjs3901 wants to merge 2 commits into
mainfrom
perf/shared-reach-every-route
Open

owjs3901 wants to merge 2 commits into
mainfrom
perf/shared-reach-every-route

Conversation

@owjs3901

Copy link
Copy Markdown
Contributor

Summary

Item 6, step 2: in a multi-route Next production build (webpack), styles that every route loads now go into the shared devup-ui.css.

Next compiles the root layout (also template and pages/_app) as an entry of its own. Atom hoisting counted it as one route, so what only the layout imports (a header, a footer) kept per-file class names and a stylesheet of its own. Every page loaded that stylesheet anyway.

withRouteShells (plugin-utils) changes only how the routes are counted:

  • Root shells. A shell that wraps every route of its router stops being a route of its own. Each route it wraps reaches it instead, through an edge added to the reach graph only. Its imports then reach every route and are hoisted under the existing threshold.
  • Nested layouts. A layout that wraps only some routes stays a route of its own, as before, so its styles never load on pages outside it. I first tried counting every layout with its routes. On a test app, the marketing pages then loaded a dashboard sidebar's CSS (+157 B), so this PR only counts shells that wrap every route.
  • Uncertain cases. Lazily loaded files and other entries keep their own routes and reach no shell, so what only they import stays per-file. App Router shells wrap page, default, not-found, forbidden, unauthorized, loading and error. _app wraps every page except api/ and _document.
  • Unchanged. Single-importer collapse plans over the graph as discovered. Dev, Turbopack (no atom hoisting yet), and apps without a layout keep their output.

The webpack plugin gets an opt-in routeShells option. Next production builds set it, while plain webpack and Rsbuild builds don't.

This PR also carries the one-route Turbopack test fix from #1033. That test (#1035) read singleCss from the loader options, which #1036 removed, so it fails on main. The hunk is identical in both PRs.

Results

Deployable bytes follow #1034's definition. Code hash is the sha256 of every .next/static and .next/server JS/CSS file, with the build ID normalized.

Benchmark Next apps (all single-route): byte-identical

Fixture Deployable Code hash
next-devup-ui 1,795,219 → 1,795,219 identical
next-devup-ui-single 1,795,389 → 1,795,389 identical
next-devup-ui-collapse 1,164,105 → 1,164,105 identical

Multi-route test app (root layout with Header and Footer, a nested dashboard layout with a Sidebar, 10 dashboard and 10 marketing pages, shared Card and Chart; webpack)

Before After
Deployable bytes 2,650,908 2,636,166 (−14,742)
Browser CSS bytes 4,520 4,454
/ CSS loaded (files) 951 B (4) 885 B (3)
/m0 CSS loaded (files) 1,101 B (3) 1,035 B (3)
/dashboard/d0 CSS loaded (files) 1,346 B (5) 1,280 B (4)
/dashboard/d0 HTML 8,122 B 7,730 B

Tests

  • route-shells.test.ts: root layout counted with its routes; nested layout or template kept as a route; _app with API routes and _document excluded; lazy and other entries untouched; a layout with no route below it kept as a route; no-shell passthrough.
  • route-shells-build.test.ts, a real webpack build with a layout entry and three pages:
    • Off: the layout's header stays per-file.
    • On: it joins devup-ui.css with short names, in cascade order. Base rules come first, then @media(min-width:768px) (responsive), then :hover (selector).
    • The header's own sheet keeps only the shared @import, and every other per-file sheet is byte-identical and still imports the shared sheet first.
    • Two builds are identical, and a build without a layout is byte-identical on and off.
  • Webpack plugin: computeFileReach gets the shell-aware routes and graph only with routeShells, and collapse still sees the discovered graph. Next plugin: production passes routeShells: true, dev passes nothing.
  • 100% coverage on the changed files; tsc and eslint pass.

요약

6번 항목 2단계입니다. 여러 라우트가 있는 Next 프로덕션 빌드(webpack)에서, 모든 라우트가 불러오는 스타일을 이제 공유 devup-ui.css에 넣습니다.

Next는 루트 layout(그리고 template, pages/_app)을 별도 엔트리로 컴파일합니다. 아톰 호이스팅은 이를 라우트 하나로 셌습니다. 그래서 레이아웃만 import하는 것(헤더, 푸터)은 per-file 클래스 이름과 자기 스타일시트를 따로 가졌고, 모든 페이지가 어차피 그 스타일시트를 불러왔습니다.

withRouteShells(plugin-utils)는 라우트를 세는 방식만 바꿉니다.

  • 루트 셸. 라우터의 모든 라우트를 감싸는 셸은 더 이상 자기 라우트가 아닙니다. 감싸는 각 라우트가 대신 셸에 도달하며, 이 edge는 도달 그래프에만 추가됩니다. 그 결과 셸이 import하는 것이 모든 라우트에 도달하고, 기존 임계값으로 호이스팅됩니다.
  • 중첩 레이아웃. 일부 라우트만 감싸는 레이아웃은 기존처럼 자기 라우트로 남습니다. 그래서 그 스타일이 바깥 페이지에서 로드되지 않습니다. 처음에는 모든 레이아웃을 라우트와 함께 셌는데, 테스트 앱에서 마케팅 페이지가 대시보드 사이드바 CSS(+157 B)를 불러오게 되어 모든 라우트를 감싸는 셸만 세도록 바꿨습니다.
  • 불확실한 경우. lazy 로드 파일과 그 밖의 엔트리는 자기 라우트를 유지하고 셸에 도달하지 않으므로, 그것들만 import하는 것은 per-file로 남습니다. App Router 셸은 page, default, not-found, forbidden, unauthorized, loading, error를 감쌉니다. _app은 api/와 _document를 뺀 모든 페이지를 감쌉니다.
  • 변화 없음. 단일 importer collapse는 발견한 그래프 그대로 계획합니다. dev, Turbopack(아직 아톰 호이스팅 없음), 레이아웃이 없는 앱은 출력이 그대로입니다.

webpack 플러그인에 opt-in 옵션 routeShells가 생겼습니다. Next 프로덕션 빌드만 켜고, 일반 webpack·Rsbuild 빌드는 켜지 않습니다.

이 PR에는 #1033의 one-route Turbopack 테스트 수정도 들어 있습니다. 이 테스트(#1035)는 로더 옵션의 singleCss를 읽었는데 #1036이 그 옵션을 없애서 main에서 실패합니다. 두 PR의 hunk는 동일합니다.

결과

배포 바이트는 #1034 정의를 따릅니다. 코드 해시는 .next/static·.next/server의 모든 JS/CSS 파일 sha256이며, 빌드 ID는 정규화했습니다.

벤치마크 Next 앱(모두 단일 라우트): 바이트 동일

Fixture 배포 바이트 코드 해시
next-devup-ui 1,795,219 → 1,795,219 동일
next-devup-ui-single 1,795,389 → 1,795,389 동일
next-devup-ui-collapse 1,164,105 → 1,164,105 동일

다중 라우트 테스트 앱 (루트 레이아웃에 Header·Footer, 중첩 dashboard 레이아웃에 Sidebar, 대시보드 10개와 마케팅 10개 페이지, 공유 Card·Chart, webpack)

전 후
배포 바이트 2,650,908 2,636,166 (−14,742)
브라우저 CSS 바이트 4,520 4,454
/ 로드 CSS(파일 수) 951 B (4) 885 B (3)
/m0 로드 CSS(파일 수) 1,101 B (3) 1,035 B (3)
/dashboard/d0 로드 CSS(파일 수) 1,346 B (5) 1,280 B (4)
/dashboard/d0 HTML 8,122 B 7,730 B

테스트

  • route-shells.test.ts: 루트 레이아웃은 라우트와 함께 셈, 중첩 레이아웃·template은 자기 라우트로 유지, _app에서 API 라우트와 _document 제외, lazy·그 밖의 엔트리는 그대로, 아래에 라우트가 없는 레이아웃은 라우트로 유지, 셸이 없으면 그대로 통과.
  • route-shells-build.test.ts, 레이아웃 엔트리와 페이지 3개로 실제 webpack 빌드:
    • 끔: 레이아웃의 헤더가 per-file로 남습니다.
    • 켬: 헤더가 짧은 이름으로 devup-ui.css에 들어가고, cascade 순서를 지킵니다. 기본 규칙 → @media(min-width:768px)(반응형) → :hover(선택자) 순입니다.
    • 헤더 자체 시트에는 공유 @import만 남고, 다른 per-file 시트는 모두 바이트 동일하며 여전히 공유 시트를 먼저 import합니다.
    • 두 빌드가 동일하고, 레이아웃이 없는 빌드는 옵션을 켜든 끄든 바이트 동일합니다.
  • webpack 플러그인: routeShells가 켜졌을 때만 computeFileReach가 셸을 반영한 라우트·그래프를 받고, collapse는 발견한 그래프를 그대로 봅니다. Next 플러그인: 프로덕션은 routeShells: true를 넘기고, dev는 아무것도 넘기지 않습니다.
  • 변경 파일 커버리지 100%이고, tsc·eslint 모두 통과합니다.

🤖 Generated with Claude Code

A production webpack build counted Next's root layout (or template, or
pages/_app) as a route of its own, so what only it imports kept a per-file
stylesheet that every page loaded anyway. A shell that wraps every route of
its router now counts with those routes when atoms are hoisted, so its imports
join the shared devup-ui.css with short names. A nested layout stays a route of
its own; lazily loaded files and other entries keep theirs. Dev, Turbopack and
plain webpack/Rsbuild builds are unchanged.

The one-route Turbopack test reads the layout from the coordinator options, as
in #1033, since #1036 removed singleCss from the loader options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
packages/next-plugin/src/plugin.ts 100.00% <100.00%> (ø)
packages/next-plugin/src/prewarm.ts 100.00% <100.00%> (ø)
packages/plugin-utils/src/import-graph.ts 100.00% <100.00%> (ø)
packages/plugin-utils/src/index.ts 100.00% <100.00%> (ø)
packages/plugin-utils/src/reservation-discovery.ts 100.00% <100.00%> (ø)
packages/plugin-utils/src/route-shells.ts 100.00% <100.00%> (ø)
packages/webpack-plugin/src/plugin.ts 100.00% <100.00%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@owjs3901
owjs3901 force-pushed the perf/shared-reach-every-route branch from cd6b29e to b28965a Compare November 19, 2026 09:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant