Files
clean-architecture-frontend…/tests/unit/design-system-initial-chunk.test.ts
T
DongHyeonka 51941a547b perf(build): 갤러리 전용 primitive를 초기 청크에서 뺀다 (1101/08-08)
문제
셸은 design-system/index.ts에서 Button·Drawer·Select를 import한다. 번들러는
배럴이 다시 내보내는 모듈을 side effect가 있다고 보고 모두 실행 순서대로
싣는다. 그래서 갤러리와 예제 화면만 쓰는 Tooltip·Menu·Toast·Tabs·Card·
Alert 등이 초기 청크(design-system-*.js)에 있다. 초기 JS는 203,818 B로
예산 204,800 B에서 982 B 남았다. 파일을 나눈 앞 커밋만으로는 바뀌지
않는다.

고른 방법
- vite.config.ts의 treeshake.moduleSideEffects 규칙으로
  src/presentation/design-system/ 아래 .ts·.tsx를 side effect 없음으로
  선언한다. 이 파일들은 컴포넌트·아이콘·토큰 목록 선언만 한다. CSS
  import는 bootstrap/main.tsx 한 곳뿐이고 이 범위 밖이다.
- 결정: 바이트를 줄인다. 예산이 걸린 지표는 바이트이고, 늘어나는 청크는
  진입 청크의 preload 목록(__vitePreload)으로 병렬로 받으므로 HTTP/2에서
  왕복이 늘지 않는다. 재검토 조건(HTTP/1.1 호스팅이면 청크 수가 비용)을
  설정 주석에 적었다.
- 새 테스트 tests/unit/design-system-initial-chunk.test.ts
  - 실제 vite build를 돌려 초기 청크에 lazy 화면 전용 클래스 13개가
    없는지 본다. 셸의 ui-drawer가 있는지를 같이 봐서 빈 결과로 통과하지
    않게 한다.
  - design-system 파일에 효과만을 위한 import(import "x")가 없는지 본다.
    선언 아래에서는 그런 import가 모듈과 함께 사라지기 때문이다.
- build-environment-bundle 테스트(13-06)는 design-system-* 청크 이름을
  찾았다. 그 청크가 없어져서, Button 코드(ui-button--pending)가 든 청크가
  build id를 바꿔도 같은지로 바꾼다. 두 build id로 빌드해 보면 바뀌는
  파일은 boot·index·render-boot-failure 셋뿐이다.
버린 대안
- 파일 분리만: 실측 효과 없음(203,824 B, 16개).
- manualChunks로 청크 이름을 고정: 제품이 primitive를 쓸 때마다 다시
  맞춰야 한다.
- 청크 수 줄이기: 15-01 청크 그룹과 같이 봤다. rolldown의 $initial 태그는
  main.tsx가 앱을 동적으로 import해서(09-03) 아무것도 잡지 않았다(25개,
  +16 B). 모듈 그래프로 boot 정적 closure를 만들면 배럴을 따라 갤러리
  primitive까지 잡혀 다시 초기 청크로 간다. 바이트 손해 없이 줄일 방법을
  찾지 못해 늘어난 수를 둔다.

위험·한계
- 초기 청크가 16개에서 25개로 는다(결정 당시 추정 21개보다 많다. 앞
  커밋의 파일 분리로 button·field·select가 따로 나온다). 전체(초기+lazy)
  gzip은 232,231 → 236,253 B로 4,022 B 는다. 첫 화면만 보는 사용자는
  2,718 B 덜 받고, 모든 화면을 도는 사용자는 청크 경계 비용만큼 더 받는다.
- 새 파일에 모듈 최상위 효과(전역 등록 등)를 넣으면 이 선언이 그 효과를
  지울 수 있다. 효과만을 위한 import는 테스트가 막지만, 최상위 문장은
  막지 않는다. 설정 주석에 적었다.
- lazy 청크 예산(청크당 122,880 B)에는 영향이 없다. 가장 큰 lazy 청크는
  8,431 B다.
- 화면 변화 없음: 같은 코드를 다른 청크에서 받는다.

검증
- RED(앞 커밋 상태): 새 테스트가 실패. 초기 청크에 ui-alert·ui-badge·
  ui-card·ui-data-table·ui-menu·ui-progress·ui-radio-group·ui-switch·
  ui-tabs·ui-toast·ui-tooltip 11개가 있었다.
- GREEN: design-system-initial-chunk·build-environment-bundle·
  design-system-contract·product-index-entrypoints·bundle-classification·
  sub-path-deployment·product-feature-selection-build 통과.
- 빌드(flock, build-frontend.ts): 초기 JS gzip 203,818 → 201,100 B
  (-2,718 B, 예산 여유 982 → 3,700 B), 초기 청크 16 → 25개, lazy 청크
  17 → 20개.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- Chromium e2e(vite preview, 위 빌드): ui-gallery·design-system-
  interactions·app-shell·accessibility·platform-overview·reference-form·
  reference-route·reference-save·theme·typography·responsive·compact-
  smoke·i18n·scroll-restoration 55/55 통과.
- tsc(app·node·test), 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
2026-11-03 01:24:31 +09:00

90 lines
3.2 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterAll, describe, expect, it } from "vitest";
import { classifyViteJavascript } from "../../scripts/lib/classify-vite-bundle.ts";
/**
* 1101/08-08. A bundler places a module, not an export, in a chunk. A
* primitive only a lazy screen renders must not ride the initial JavaScript
* because it shares a file, or the barrel, with one the app shell renders.
*/
const DESIGN_SYSTEM = "src/presentation/design-system";
// Classes that only the primitives the template's lazy screens use render.
const LAZY_ONLY_CLASSES = Object.freeze([
"ui-alert",
"ui-badge",
"ui-breadcrumbs",
"ui-card",
"ui-data-table",
"ui-menu",
"ui-popover",
"ui-progress",
"ui-radio-group",
"ui-switch",
"ui-tabs",
"ui-toast",
"ui-tooltip",
]);
const roots: string[] = [];
afterAll(async () => {
await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
});
async function initialJavascript(): Promise<string> {
const outDir = await mkdtemp(path.join(tmpdir(), "design-system-chunk-"));
roots.push(outDir);
const environment = Object.fromEntries(
Object.entries(process.env).filter(([name]) => !name.startsWith("VITE_")),
);
const run = spawnSync(
path.resolve("node_modules/.bin/vite"),
["build", "--outDir", outDir, "--emptyOutDir", "--logLevel", "error"],
{ encoding: "utf8", env: environment },
);
expect(run.stderr).toBe("");
expect(run.status).toBe(0);
const manifest = JSON.parse(
await readFile(path.join(outDir, ".vite/manifest.json"), "utf8"),
) as Parameters<typeof classifyViteJavascript>[0];
const { initialFiles } = classifyViteJavascript(manifest);
const sources = await Promise.all(
initialFiles.map((file) => readFile(path.join(outDir, file), "utf8")),
);
return sources.join("\n");
}
const renders = (code: string, className: string) =>
new RegExp(`(?<![\\w-])${className}(?![\\w-])`, "u").test(code);
describe("design-system code in the initial JavaScript (1101/08-08)", () => {
it("leaves the primitives only lazy screens use out of the initial chunks", async () => {
const code = await initialJavascript();
// The shell's drawer is initial; without it the check proves nothing.
expect(renders(code, "ui-drawer")).toBe(true);
expect(LAZY_ONLY_CLASSES.filter((name) => renders(code, name))).toEqual([]);
}, 120_000);
// vite.config.ts declares these modules free of side effects, so the bundler
// drops a module none of whose exports is used. An import kept only for its
// effect (a stylesheet, a polyfill, a registration) would vanish with it.
it("keeps every design-system module free of imports kept for their effect", async () => {
const files = (await readdir(DESIGN_SYSTEM, { recursive: true }))
.filter((file) => /\.tsx?$/u.test(file) && !file.includes(".stories."));
expect(files.length).toBeGreaterThan(0);
const offenders: string[] = [];
for (const file of files) {
const source = await readFile(path.join(DESIGN_SYSTEM, file), "utf8");
if (/^\s*import\s*["']/mu.test(source)) offenders.push(file);
}
expect(offenders).toEqual([]);
});
});