Skip to content

fix(next-plugin): fail a build whose coordinator CSS is incomplete - #938

Merged
owjs3901 merged 2 commits into
mainfrom
fix/next-partial-css
Nov 17, 2026
Merged

owjs3901 merged 2 commits into
mainfrom
fix/next-partial-css

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes audit item NXT-15 (P1, WRONG). When the coordinator's /css?waitForIdle=true wait ended on the quiet window (quietMs) or the hard timeout (maxWaitMs), it served the incomplete bucket/base sheet as is with HTTP 200. Production Turbopack builds bundle this first response as the stylesheet, so if some files had not been extracted, CSS with class names but no rules could ship as a successful build.

  • waitForBase / waitForBucket now also return the reason when they give up.
  • In that case /css responds with 500 and a message listing the files that were not extracted. ([devup-ui] coordinator: bucket "src/bucket.tsx" is incomplete (no extraction for 10000ms); refusing to serve partial CSS. Files not extracted: src/m1.tsx.)
  • The CSS loader includes the body of a non-200 response in the loader error, so the Turbopack build fails with that reason.
  • The wait only happens in builds (the CSS loader in next dev does not send waitForIdle). So dev mode behavior does not change and no separate dev-only fallback is needed.
  • The idle heuristic used when there is no expected file set still responds with 200. However, if it does not become idle by maxWaitMs in that state, it is now an error.
  • The plugin's production path prewarms the whole route closure, so a normal build does not reach this error path. Only when the prewarm set and the loaders disagree does the build now fail instead of silently breaking.

Overlap with other PRs

Test plan

  • bun test --coverage (next-plugin: coordinator, css-loader, loader, plugin, coordinator-port, prewarm): coordinator.ts, css-loader.ts at 100% lines / functions
    • If a bucket member is never extracted, 500 + list of missing files after maxWaitMs (getCss not called)
    • After the quiet window, 500 + list of missing files for both bucket / base
    • With no expected file set and no extraction, timeout → 500 (no file list)
    • The CSS loader includes the coordinator body in the error, and shows only the status code when the body is empty
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (changed files)
  • Locally, 3 tests in plugin.test.ts (native engine / seedFileMap) fail the same way on main too, because of stale WASM / native builds.

요약

감사 항목 NXT-15 (P1, WRONG) 수정입니다. 코디네이터의 /css?waitForIdle=true 대기가 quiet window(quietMs)나 hard timeout(maxWaitMs)으로 끝나면, 완료되지 않은 버킷/베이스 시트를 그대로 HTTP 200으로 응답했습니다. 프로덕션 Turbopack 빌드는 이 첫 응답을 스타일시트로 번들링하므로, 추출되지 않은 파일이 있으면 클래스 이름만 있고 규칙이 없는 CSS가 성공한 빌드로 배포될 수 있었습니다.

  • waitForBase / waitForBucket이 포기할 때 이유를 함께 반환하도록 바꿨습니다.
  • 이 경우 /css는 500과 함께 추출되지 않은 파일 목록을 담은 메시지를 응답합니다. ([devup-ui] coordinator: bucket "src/bucket.tsx" is incomplete (no extraction for 10000ms); refusing to serve partial CSS. Files not extracted: src/m1.tsx.)
  • CSS 로더는 비-200 응답의 본문을 로더 에러에 포함해, Turbopack 빌드가 그 이유와 함께 실패합니다.
  • 대기는 빌드에서만 일어납니다 (next dev의 CSS 로더는 waitForIdle을 보내지 않음). 따라서 개발 모드 동작은 바뀌지 않으며 별도의 dev 전용 fallback은 필요하지 않습니다.
  • 기대 파일 집합이 없을 때 쓰는 idle 휴리스틱은 그대로 200을 응답합니다. 다만 그 상태에서 maxWaitMs까지 idle이 되지 않으면 이제 에러입니다.
  • 플러그인의 프로덕션 경로는 route closure 전체를 prewarm하므로 정상 빌드에서는 이 에러 경로에 도달하지 않습니다. prewarm 집합과 로더가 어긋나는 경우에만 조용히 깨지는 대신 빌드가 실패합니다.

다른 PR과의 겹침

테스트 계획

  • bun test --coverage (next-plugin: coordinator, css-loader, loader, plugin, coordinator-port, prewarm): coordinator.ts, css-loader.ts 100% lines / functions
    • 버킷 멤버가 끝내 추출되지 않으면 maxWaitMs 후 500 + 누락 파일 목록 (getCss 미호출)
    • quiet window 후 버킷 / 베이스 모두 500 + 누락 파일 목록
    • 기대 파일 집합이 없고 추출도 없을 때 timeout → 500 (파일 목록 없음)
    • CSS 로더가 코디네이터 본문을 에러에 포함하고, 본문이 비면 상태 코드만 표시
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (변경 파일)
  • 로컬에서 plugin.test.ts의 3개 테스트(native 엔진 / seedFileMap)는 오래된 WASM / native 빌드 때문에 main에서도 동일하게 실패합니다.

Refs #686

🤖 Generated with Claude Code

The coordinator's /css wait used to give up after a quiet window or its
hard timeout and still answer 200 with whatever the sheet held. A build
bundles that first answer as its stylesheet, so a missing file shipped
class names without their rules and the build reported success.

The base and bucket waits now resolve with a reason when they give up,
and /css answers 500 with a message naming the files that never
extracted. The CSS loader passes the coordinator's reason into the
loader error, so Turbopack fails the build with it. Only builds wait;
next dev never asks to, so development behaviour is unchanged. The
idle heuristic used when no expected file set exists still answers 200.

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

css-loader.ts now reaches the coordinator through callCoordinator (#917);
keep this branch's status-plus-reason error message on top of reply.body.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@owjs3901
owjs3901 merged commit 25cbf65 into main Nov 17, 2026
27 checks passed
@owjs3901
owjs3901 deleted the fix/next-partial-css branch November 17, 2026 07:30
owjs3901 added a commit that referenced this pull request Nov 17, 2026
Resolve the conflict with #938 in packages/next-plugin/src/coordinator.ts.
#938 adds no new module state: its error-returning waitForBase and
waitForBucket, missingFiles and incompleteCssError now read the app's own
CoordinatorState, so one app's extractions never complete another app's
CSS. A test covers two apps expecting the same base files. #939's
shared-slot reservation runs on the app's own engine session; its test
now expects that session instead of the shared engine.

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