perf(build): react-dom을 자기 청크로 빼 build id만 바뀐 release의 캐시 손실을 줄인다

문제: build id는 부트 실패 화면이 보여 주므로 render-boot-failure 청크에
들어간다. react-dom과 scheduler(약 56 KB gzip)가 같은 청크에 있어서
build id만 다른 두 빌드에서 boot·index·render-boot-failure 세 파일의
이름이 바뀌었다. 합계 99,785 B로 초기 JS의 49.4%다. 해시 자산은 1년
immutable로 캐시되는데, 재방문 사용자는 코드가 같아도 release마다 이만큼
다시 받았다. 1101 O1이 같은 것을 재고 채택을 권했지만 결정 기록이 없었다.

고른 방법: codeSplitting.groups에 react-dom·scheduler 그룹을 더한다
(includeDependenciesRecursively: false라 라이브러리 모듈만 묶는다).
같은 비교에서 바뀐 초기 JS가 44,297 B(22.0%)로 준다. 초기 JS는
201,857 → 201,552 B, 초기 파일 수는 25개 그대로다(react-dom 진입
모듈 1.3 KB 청크가 합쳐졌다).
버린 대안: build id를 JS에 넣지 않고 release-manifest.json에서만 읽기.
boot까지 바뀌지 않아 더 줄지만, 부트 실패 화면이 build id를 보여 주는
계약을 바꿔야 한다.

위험·한계: boot(39 KB)는 build id로 설정을 대조하므로 계속 바뀐다.
그룹 정규식은 pnpm의 node_modules 배치를 가정한다. 배치가 바뀌어 그룹이
비면 새 테스트가 실패한다.

검증: tests/unit/build-environment-bundle.test.ts가 build id만 다른 두
빌드에서 react-dom이 든 청크의 이름이 같고 그 청크가
render-boot-failure가 아님을 본다(고치기 전 실패). 부트 실패 화면
e2e(tests/e2e/boot-module-failure.spec.ts, chromium) 통과.
feature-shape-growth·design-system-initial-chunk·bundle-classification
통과. 두 빌드 비교는 docs/operations/performance-evidence.md에 기록했다.

Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-06
This commit is contained in:
DongHyeonka
2026-11-04 20:23:54 +09:00
parent 46dfe23f69
commit af6d0a9f01
3 changed files with 52 additions and 0 deletions
+26
View File
@@ -161,3 +161,29 @@ the example can never serve as production evidence.
파일을 늘리는 변경은 그 값을 같이 고치고, 이유를 같은 변경에 적는다. HTTP/1.1로만 서빙해야 하는
제품은 (나)처럼 초기 청크를 묶는 그룹을 `vite.config.ts`에 넣는다. 그 목록은
셸을 바꿀 때마다 위 방법으로 다시 잰다.
## build id와 재방문 캐시
리뷰 1103/15-06(1101 O1, 0929/13-03). build id는 부트 실패 화면이 보여 주므로
그 청크에 들어간다. 해시 자산은 1년 `immutable`로 캐시되지만, build id가 든
청크와 그 청크를 import하는 청크는 release마다 이름이 바뀐다. react-dom이 그
청크 안에 있을 때는 코드가 같아도 release마다 초기 JS의 절반을 다시 받았다.
판단: react-dom과 scheduler를 자기 청크(`vite.config.ts`의 `react-dom` 그룹)로
뺀다. 2026-11-04 `VITE_BUILD_ID`만 다른 두 빌드(`gitea-101-1`, `gitea-102-1`)를
비교했다.
| 빌드 | 이름이 바뀐 초기 파일 | 바뀐 초기 JS gzip(B) | 초기 JS gzip(B) | 초기 파일 |
|---|---|---:|---:|---:|
| 분리 전 | `boot`, `index`, `render-boot-failure` | 99,785 (49.4%) | 201,857 | 25 |
| 분리 뒤 | `boot`, `index`, `render-boot-failure` | 44,297 (22.0%) | 201,552 | 25 |
- lazy 파일은 두 경우 모두 0 B 바뀐다.
- 초기 파일 수는 그대로다. react-dom의 작은 진입 모듈(1.3 KB)이 같은 청크로
합쳐졌다.
- `boot`는 build id로 설정 문서를 대조하므로 계속 바뀐다. build id를 JS에 넣지
않고 `release-manifest.json`에서만 읽으면 더 줄지만, 부트 실패 화면이 build
id를 보여 주는 계약을 바꿔야 해서 하지 않았다.
- 부트 실패 화면은 여전히 앱 그래프의 모듈 없이 그려진다(09-03,
`tests/e2e/boot-module-failure.spec.ts`). 이름이 유지되는지는
`tests/unit/build-environment-bundle.test.ts`가 본다.
@@ -78,6 +78,18 @@ describe("build variables in the bundle (13-06)", () => {
const firstChunks = designSystem(first);
expect(firstChunks).toHaveLength(1);
expect(designSystem(second)).toEqual(firstChunks);
// 1103/15-06. react-dom is about 56 KB of the initial JavaScript. It sat
// in the boot-failure chunk with the build id, so every release renamed
// it and returning visitors downloaded it again. Its own chunk keeps the
// name while only the build id changes.
const reactDom = ({ contents }: Awaited<ReturnType<typeof build>>) =>
contents
.filter(({ file, text }) => file.endsWith(".js") && text.includes("__reactContainer$"))
.map(({ file }) => path.basename(file));
expect(reactDom(first)).toHaveLength(1);
expect(reactDom(first)[0]).not.toMatch(/render-boot-failure/u);
expect(reactDom(second)).toEqual(reactDom(first));
}, 120_000);
it("refuses a VITE_* variable the build does not declare", async () => {
+14
View File
@@ -182,6 +182,20 @@ export default defineConfig(({ mode }) => {
// chunk would import the entry, whose hash changes with each
// build id.
{ name: "preload-helper", test: /vite[\\/]preload-helper/ },
// 1103/15-06. react-dom and scheduler (about 56 KB gzip) shared
// the boot-failure chunk with the build id, so a release that
// only changed the build id renamed half of the initial
// JavaScript (99,785 of 201,857 B) and returning visitors
// downloaded it again. In a chunk of their own they keep their
// name: the same change renames 44,297 B (boot, entry and the
// boot-failure screen, which hold or import the build id).
// The boot-failure screen still needs no module of the
// application graph (09-03): this chunk is a library leaf.
{
name: "react-dom",
test: /[\\/]node_modules[\\/](?:\.pnpm[\\/][^\\/]+[\\/]node_modules[\\/])?(?:react-dom|scheduler)[\\/]/,
includeDependenciesRecursively: false,
},
// 1101/07-03. Every feature's schemas and runtime half import
// the shared zod adapter. Alone it becomes a chunk of its own
// once two features share it, and every route and runtime