Skip to content

perf(next-plugin): keep the setup state and local paths out of the serialized Turbopack config - #1036

Merged
owjs3901 merged 4 commits into
mainfrom
perf/turbo-compact-config
Nov 19, 2026
Merged

owjs3901 merged 4 commits into
mainfrom
perf/turbo-compact-config

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Next serializes the resolved next.config into .next/required-server-files.{js,json}, and that file ships with the app (next start reads it). The Turbopack rules of @devup-ui/next-plugin carried the whole setup state in both loaders' options: default sheet, class map, file map, theme, state file paths, import aliases and absolute local paths (C:\Users\...). That part grew with the app.

Every Turbopack loader call runs in coordinator mode (coordinatorPortFile is always set), and in that mode the loaders read only the port file and the theme files. The rules now pass only:

  • coordinatorPortFile: relative, as before.
  • themeFiles: now relative to the project root. The loaders resolve() them before addDependency, so dev/HMR watches the same files.
  • watch: CSS loader only; it decides waitForIdle.
  • stateKey: a 16-hex sha256 of everything the options used to hold.

stateKey keeps Turbopack's loader-cache invalidation as before: when that state changes, the options change and the loaders re-run.

The loader option types are now a union of coordinator and standalone options. The standalone (non-coordinator) path is unchanged. The webpack path adds nothing to the serialized config: only webpack, a function, differs from the tailwind build, and it is dropped from the JSON.

Results

Deployable bytes use #1034's definition (no .next/cache, build/, types/, diagnostics/, trace, *.nft.json, *.tsbuildinfo, *.map). Code hash is the sha256 of every .next/static and .next/server JS/CSS file, with the build ID normalized.

Fixture Deployable before Deployable after Δ required-server-files before → after Code hash
next-devup-ui-single-turbo 1,388,711 1,366,951 −21,760 44,743 → 22,983 identical
next-devup-ui-turbo 1,389,184 1,366,932 −22,252 45,203 → 22,951 identical
next-devup-ui-large-turbo 2,688,159 2,602,739 −85,420 108,395 → 22,975 identical
next-tailwind-turbo-devup-ui 1,389,951 1,367,141 −22,810 45,801 → 22,991 identical
next-stylex-turbo-devup-ui 1,095,524 1,072,712 −22,812 45,795 → 22,983 identical

config.turbopack is 4,013 B before (single) and up to ~43 KB before (large). After, it is 496 B on every fixture, independent of app size, with no Devup absolute path. The remaining root is Next's own and is present in the tailwind build too.

Same machine, next-tailwind-turbo: 1,368,505 B. next-devup-ui-single-turbo is now 1,366,951 B, smaller than Tailwind (it was 20 KB larger).

Remaining entries

The two rule entries that remain (about 500 B, constant, no local path) live in Next's server-side config snapshot (required-server-files.{js,json} and the standalone server.js). They cannot be removed safely today. Next deep-copies the config before compiler.runAfterProductionCompile runs, and the hook receives no config. The only Next option that filters bundler settings out of the snapshot (experimental.runtimeServerDeploymentId) makes the server throw without NEXT_DEPLOYMENT_ID and pins prerendered chunk URLs to the build-time id (vercel/next.js#98078). Upstream request: vercel/next.js#102045. The README and the limitations docs describe this.


요약

Next는 해석된 next.config를 .next/required-server-files.{js,json}에 직렬화합니다. 이 파일은 앱과 함께 배포되며 next start가 읽습니다. 그동안 @devup-ui/next-plugin의 Turbopack 규칙은 두 로더 옵션에 설정 상태 전체를 담고 있었습니다. 기본 시트, 클래스 맵, 파일 맵, 테마, 상태 파일 경로, import alias, 로컬 절대 경로(C:\Users\...)가 들어 있었고, 이 부분은 앱이 커질수록 함께 커졌습니다.

Turbopack 로더는 항상 coordinator 모드로 실행됩니다(coordinatorPortFile이 항상 설정됨). 이 모드의 로더는 포트 파일과 테마 파일만 읽습니다. 그래서 규칙에는 이제 다음만 넘깁니다.

  • coordinatorPortFile: 기존과 같이 상대 경로입니다.
  • themeFiles: 이제 프로젝트 루트 기준 상대 경로입니다. 로더가 addDependency 전에 resolve()하므로 dev/HMR은 같은 파일을 감시합니다.
  • watch: CSS 로더만 받으며, waitForIdle을 정합니다.
  • stateKey: 기존 옵션 내용 전체의 sha256 앞 16자리입니다.

stateKey 덕분에 Turbopack 로더 캐시 무효화는 기존과 같습니다. 상태가 바뀌면 옵션이 바뀌고 로더가 다시 실행됩니다.

로더 옵션 타입은 coordinator/standalone 유니온으로 바꿨고, standalone 경로는 그대로입니다. webpack 경로는 직렬화 config에 추가하는 것이 없습니다. tailwind 빌드와 다른 키는 함수인 webpack뿐이고, 함수는 JSON에서 빠집니다.

결과

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

Fixture 배포 전 배포 후 Δ required-server-files 전 → 후 코드 해시
next-devup-ui-single-turbo 1,388,711 1,366,951 −21,760 44,743 → 22,983 동일
next-devup-ui-turbo 1,389,184 1,366,932 −22,252 45,203 → 22,951 동일
next-devup-ui-large-turbo 2,688,159 2,602,739 −85,420 108,395 → 22,975 동일
next-tailwind-turbo-devup-ui 1,389,951 1,367,141 −22,810 45,801 → 22,991 동일
next-stylex-turbo-devup-ui 1,095,524 1,072,712 −22,812 45,795 → 22,983 동일

config.turbopack은 이전 4,013 B(single)에서 최대 약 43 KB(large)였습니다. 이제 모든 fixture에서 496 B이고 앱 크기와 무관하며, Devup 절대 경로도 없습니다. 남은 root는 Next 자체 값이며 tailwind 빌드에도 있습니다.

같은 머신에서 next-tailwind-turbo는 1,368,505 B입니다. next-devup-ui-single-turbo는 이제 1,366,951 B로 Tailwind보다 작습니다(이전에는 20 KB 더 컸음).

남은 항목

남은 규칙 두 개(약 500 B, 고정 크기, 로컬 경로 없음)는 Next의 서버 쪽 config 스냅샷(required-server-files.{js,json}, standalone server.js)에 들어 있습니다. 지금은 안전하게 지울 방법이 없습니다. Next는 compiler.runAfterProductionCompile 실행 전에 config를 깊은 복사하고, 이 훅은 config를 받지 못합니다. 스냅샷에서 번들러 설정을 거르는 유일한 Next 옵션(experimental.runtimeServerDeploymentId)은 NEXT_DEPLOYMENT_ID 없이 서버가 예외를 던지게 하고, 프리렌더 청크 URL을 빌드 시점 id에 고정합니다(vercel/next.js#98078). 업스트림 요청: vercel/next.js#102045. README와 limitations 문서에도 적었습니다.

🤖 Generated with Claude Code

owjs3901 and others added 2 commits November 19, 2026 15:20
…ck config

Next serializes the resolved next.config into .next/required-server-files.{js,json},
which ships with the app. Every Turbopack loader call runs in coordinator mode, so
the rules now pass only the port file, the theme files (and watch for the CSS
loader) plus a short hash of the state they used to carry, which still re-keys
Turbopack's loader cache when that state changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the project root

The serialized config shipped absolute local paths (C:\Users\...). The loaders run
in the project root and resolve the relative paths before adding them as
dependencies, so dev and HMR still watch the same files.

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/css-loader.ts 100.00% <100.00%> (ø)
packages/next-plugin/src/loader.ts 100.00% <100.00%> (ø)
packages/next-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.

owjs3901 and others added 2 commits November 19, 2026 15:49
…fig snapshot

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@owjs3901
owjs3901 merged commit 409af00 into main Nov 19, 2026
37 checks passed
@owjs3901
owjs3901 deleted the perf/turbo-compact-config branch November 19, 2026 07:42
owjs3901 added a commit that referenced this pull request Nov 19, 2026
…ions

The Turbopack loader options no longer carry singleCss (#1036), so the
one-route test (#1035) checks what the coordinator extracts into.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
owjs3901 added a commit that referenced this pull request Nov 19, 2026
…rs (#1033)

* perf(plugins): read each source once across the prepasses and compilers

The import graph, the class-slot reservation and the prewarm each read the
project's sources from disk, and a Next production build runs all of them
again for its server, edge and client compilers. They now read through a
stamp-checked cache that one build shares: plugin-utils' `readSource` serves
a file again from the cache while its modification stamp is unchanged, inside
`withSourceCache`. Next hands one cache to the webpack plugins of all its
production compilers and uses one for the Turbopack setup; a plain webpack
build shares one per preparation. Watch and dev builds still start from a
fresh cache for each compilation. The module resolver keeps its own cache and
reads misses through the shared one.

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

* test(next-plugin): read the one-route layout from the coordinator options

The Turbopack loader options no longer carry singleCss (#1036), so the
one-route test (#1035) checks what the coordinator extracts into.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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