Skip to content

perf(next-plugin): cache the coordinator's latest extraction per file - #946

Merged
owjs3901 merged 3 commits into
mainfrom
fix/next-transform-cache
Nov 17, 2026
Merged

owjs3901 merged 3 commits into
mainfrom
fix/next-transform-cache

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fix for audit item NXT-13 (P2, PERF). Next compiles a module imported by both the server graph and the client graph once per graph, with the same source, in no guaranteed order. next dev has no prewarm results, so the second /extract also re-ran WASM every time and rewrote the CSS / state files, even though the styles were already in the sheet.

  • The coordinator remembers the latest extraction result per file, together with:
    • the source code
    • the CSS directory (relCssDir)
    • the mtime / size of the files the extraction read through the module resolver (dependencies)
  • A request with the same source, the same CSS directory and unchanged dependencies is answered from the cache. Like a prewarm hit, it rewrites nothing.
  • Only the latest source is kept per file.
    • The cache size is bounded by the number of project files.
    • A cache hit guarantees that the sheet holds exactly that source's styles. Going back, as in v1 → v2 → v1, re-extracts (because the sheet has v2's styles).
  • When an extraction fails, that file's cache entry is removed, so it never answers with an entry whose engine state may have changed.
  • In production the existing prewarm cache applies first, then this cache. Cleared in startCoordinator / resetCoordinator.

Overlap with other PRs

Test plan

  • bun test --coverage src/__tests__/coordinator.test.ts: coordinator.ts 100% lines / functions
    • Extracting the same source twice runs WASM only once, and the second request returns the same result without writing
    • Re-extracts when the source changes, returns to a previous source, or the CSS directory differs
    • Re-extracts when a dependency file changes or a previously missing dependency appears
    • After a failed extraction, a request with the same source re-extracts instead of hitting the cache
    • After a theme reload, an unchanged source re-extracts, and the new output is cached again (fails if the transformCache.clear() in refreshTheme is removed)
  • next-plugin plugin.test.ts, loader.test.ts
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (changed files)

요약

감사 항목 NXT-13 (P2, PERF) 수정입니다. Next는 server 그래프와 client 그래프가 모두 import하는 모듈을 그래프마다 한 번씩, 같은 소스로, 순서 보장 없이 컴파일합니다. next dev에는 prewarm 결과가 없으므로 두 번째 /extract도 매번 WASM을 다시 실행하고 CSS / state 파일을 다시 썼습니다. 스타일은 이미 시트에 들어 있는데도 그랬습니다.

  • 코디네이터가 파일별 최신 추출 결과를 다음 정보와 함께 기억합니다.
    • 소스 코드
    • CSS 디렉터리(relCssDir)
    • 추출이 module resolver로 읽은 파일들(dependencies)의 mtime / size
  • 같은 소스, 같은 CSS 디렉터리이고 dependency가 그대로인 요청은 캐시에서 응답합니다. prewarm hit과 같이 아무것도 다시 쓰지 않습니다.
  • 파일마다 최신 소스 하나만 보관합니다.
    • 캐시 크기는 프로젝트 파일 수로 제한됩니다.
    • 캐시 hit이면 시트가 정확히 그 소스의 스타일을 갖고 있다는 것이 보장됩니다. v1 → v2 → v1처럼 되돌아가면 다시 추출합니다 (시트에는 v2의 스타일이 있기 때문).
  • 추출이 실패하면 그 파일의 캐시 항목을 지워, 엔진 상태가 바뀌었을 수 있는 항목으로 응답하지 않습니다.
  • 프로덕션의 기존 prewarm 캐시가 먼저 적용되고, 그 다음이 이 캐시입니다. startCoordinator / resetCoordinator에서 비웁니다.

다른 PR과의 겹침

  • fix(next-plugin): reload the Turbopack theme when devup.json changes #944 (NXT-11, theme reload, 머지됨): main 머지에서 해결했습니다. theme 토큰이 추출 결과에 들어가므로, theme 입력 파일이 바뀌면 refreshTheme()가 reload 전에 transformCache.clear()를 호출합니다 (예외를 던진 reload도 등록된 theme을 이미 바꿨을 수 있기 때문). startCoordinator / resetCoordinator는 캐시와 theme watch를 함께 초기화하고, dependency와 theme stamp는 하나의 fileStamp 헬퍼를 공유합니다.
  • fix(next-plugin): fail a build whose coordinator CSS is incomplete #938 (NXT-15)과 #929는 같은 coordinator.ts의 다른 부분(대기 함수 / 종료 쓰기)을 수정하므로 텍스트 충돌만 가능합니다.

테스트 계획

  • bun test --coverage src/__tests__/coordinator.test.ts: coordinator.ts 100% lines / functions
    • 같은 소스로 두 번 추출하면 WASM은 한 번만 실행되고, 두 번째는 쓰기 없이 같은 결과를 응답
    • 소스가 바뀌거나 이전 소스로 돌아가거나 CSS 디렉터리가 다르면 다시 추출
    • dependency 파일이 바뀌거나, 없던 dependency가 생기면 다시 추출
    • 추출 실패 후 같은 소스 요청은 캐시가 아니라 다시 추출
    • theme reload 후에는 같은 소스도 다시 추출하고, 새 결과를 다시 캐시 (refreshTheme의 transformCache.clear()를 빼면 실패)
  • next-plugin plugin.test.ts, loader.test.ts
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (변경 파일)

Refs #686

🤖 Generated with Claude Code

Next compiles a module that both the server and the client graph import
once per graph, with the same source. In next dev nothing was
prewarmed, so every /extract ran the engine again and rewrote the CSS
and state files even though the styles were already in the sheet.

The coordinator now keeps the latest extraction of each file with its
source, CSS directory and the mtime and size of the files the
extraction read through the module resolver. A request with the same
source and CSS directory whose dependencies are unchanged is answered
from it and, like a prewarm hit, writes nothing. Only the latest source
per file is kept, so the cache is bounded by the file count and a hit
always means the sheet holds exactly that source's styles; going back
to an earlier source extracts again. A failing extraction drops the
file's entry.

Refs #686

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

codecov Bot commented Nov 15, 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/coordinator.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 16, 2026 08:06
coordinator.ts: import both existsSync (main, deleted-source removal from
#951) and statSync (dependency stamps). When main's removeDeletedSources
forgets a deleted file, it now drops that file's transform cache entry too:
the file's styles leave the sheet, so a restored file with the same source
must extract again instead of answering from the cache.

coordinator.test.ts: keep both new describe blocks (transform cache,
deleted sources), and add a test that a deleted file restored unchanged is
extracted again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the coordinator against #944. refreshTheme clears the transform
cache before it reloads the theme, so no extraction cached under the old
theme survives a devup.json change; startCoordinator and resetCoordinator
reset both the cache and the theme watch, and the cache entry of a deleted
file is still dropped. The dependency and theme stamps share one
fileStamp helper. A new test proves a theme reload invalidates the cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@owjs3901
owjs3901 merged commit 84a4f33 into main Nov 17, 2026
27 checks passed
@owjs3901
owjs3901 deleted the fix/next-transform-cache branch November 17, 2026 07:08
owjs3901 added a commit that referenced this pull request Nov 17, 2026
Resolve the conflict with #946 in packages/next-plugin/src/coordinator.ts.
The transform cache becomes per app: it lives in each app's
CoordinatorState next to extractedSources, a theme refresh clears only
that app's cache, and a removed source drops only the owning app's entry.
themeStamp is replaced by #946's fileStamp. Adds a test that two apps
never share cached extractions.

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