문제
initialJsFiles 상한이 템플릿 그대로의 수(26)와 같다(1b8cb12). 기능의 지연
페이지가 셸과 같은 구성요소(Button, SearchField)를 쓰면 그 구성요소가 공유
청크로 떨어져 초기 파일이 하나 는다. 매뉴얼의 검색 폼 예제를 따른 기능
하나로 FE-GATE-012가 "27 > budget 26"으로 실패했다(리뷰 조치 X2 #4).
고른 방법
- 상한을 32(지금 26 + 6)로 둔다. 템플릿은 HTTP/2 서빙을 요구하고
(1103/13-02, FE-GATE-019), 그때 파일 하나의 비용은 거의 없다(15 영역
측정). 상한은 청크가 통째로 쪼개지는 회귀를 막는 용도다.
- performance-evidence.md에 이유와, 넘었을 때 먼저 청크 그룹을 볼 것을
적는다.
- 버린 대안: 상한을 지금 수로 두고 제품마다 올리기. 템플릿 소유 파일을
기능마다 고치게 된다.
위험·한계
- 합계 바이트 예산(204,800 B)은 그대로다. 여유는 1,873 B다.
검증
- performance-budgets·bundle-artifact-contract 테스트 14건,
verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/15-performance.md 15-05, README.md 14.6 X2 #4
13 KiB
Performance evidence contract
Performance evidence is deliberately split by measurement context:
bundle.jsonrecords production build output and enforces initial JavaScript at 200 KiB gzip, the number of initial JavaScript files (initialJsFiles), and every lazy chunk at 120 KiB gzip. A failure names each exceeded limit, the measured value and the excess (1103/15-03).lab.jsonrecords Chromium/runner/viewport/network/CPU/cache/build context and enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.field-web-vitals.jsonrecords consent-filtered, route-ID aggregated, release-specific production samples over 28 days and evaluates p75 LCP, CLS, and INP against 2.5 s, 0.10, and 200 ms.
번들 예산의 기준선과 여유
리뷰 0925/13-14, 1101/15-02, 1103/15-02. 예산은 config/performance/budgets.json에
있고 scripts/check-bundle.ts(FE-GATE-012, merge 단계)가 강제한다. 템플릿 기본
화면만으로 초기 JS 예산의 대부분을 쓴다. 첫 기능을 추가하기 전에 아래 기록을
보고 예산을 정한다.
기준선 숫자는 이 문서에 적지 않는다. 손으로 적은 숫자는 두 번 낡았다. 기록은
config/scale/feature-shape-ceilings.json의 initialJavascript 한 곳이다. 이 파일과 아래
측정 테스트는 참조 기능을 복사해 재므로 샘플과 함께 지워진다. 그래서 경로를 백틱 없이 적는다.
| 칸 | 뜻 |
|---|---|
gzipBytes, files |
템플릿 그대로의 초기 JS gzip bytes와 파일 수(entry 포함) |
perFeatureGzipBytes |
있는 context에 참조 기능 모양 기능을 하나 더할 때 느는 초기 JS. 상한 1 KiB |
perContextGzipBytes |
새 context를 하나 더할 때 느는 초기 JS. 상한 512 B |
- tests/unit/feature-shape-growth.test.ts(unit, merge 단계)가 매번 빌드해 이 값을 재고, 상한을 넘거나 기록과 다르면(합계 1% 초과, 파일 수 불일치, 기능· context 비용 10% 초과) 실패한다. 실패 메시지에 잰 값이 나온다.
- 기록을 고칠 때는
node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write를 돌리고 같은 변경에 넣는다. - 여유는 예산에서
gzipBytes를 뺀 값이다. 그것을perFeatureGzipBytes로 나누면 더 넣을 수 있는 기능 수다. 새 context마다perContextGzipBytes가 더 든다. - 기능 실행부(
feature-runtime.ts)는 라우트에 들어갈 때 받는 lazy chunk다. lazy chunk 예산은 파일마다 120 KiB(lazyChunkGzipBytes)다.
청크 이름으로 크기를 판단하지 않는다. rolldown은 공용 청크에 안에 든 모듈
하나의 이름을 붙인다. 아래는 2026-11-01(298201f)에 잰 출처별 크기다. 지금
빌드와는 조금 다르다. sourcemap 빌드에서 minify된 바이트를 원래 모듈에 나눠
붙이고 묶음마다 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다.
| 출처 | minify bytes | 단독 gzip bytes |
|---|---|---|
| react-dom + scheduler | 181,673 | 56,545 |
| react-router | 94,271 | 30,697 |
| zod | 70,512 | 18,607 |
| @tanstack/* | 24,751 | 7,286 |
| react | 7,869 | 2,961 |
| 그 밖의 npm(lucide-react) | 2,329 | 1,142 |
템플릿 src |
265,529 | 78,883 |
템플릿 src 중 큰 것은 src/contracts 17.8 KB, src/adapters/http 8.0 KB,
src/presentation/i18n(문구 카탈로그) 7.6 KB, src/bootstrap 7.4 KB,
src/presentation/design-system 5.1 KB다.
측정 조건:
- 초기 파일은 Vite manifest의 entry, 그 static import, entry가 직접 dynamic
import하는 chunk(
boot,render-boot-failure)와 그 static import다 (scripts/lib/classify-vite-bundle.ts). entry는 앱 그래프의 평가 실패를 보고하려고 그 둘을 dynamic import로 읽을 뿐이고, 첫 화면에 항상 필요하다 (0925/09-03). 그 밖의 dynamic import chunk는 lazy다. - 합계는 JavaScript만 센다. CSS(
index-*.css)는 예산에 들어가지 않는다. - gzip은 Node
zlib.gzipSync기본 수준(6)으로 잰다 (scripts/lib/release-candidate.ts). 호스팅이 brotli로 보내면 전송 크기는 더 작다. 예산은 gzip 기준 그대로 둔다. - Node·pnpm·runner 이미지는
artifacts/performance/bundle.json의context에 기록된다.
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
lab 측정(scripts/test-performance.ts, FE-GATE-026)은 local 프로필 build를
vite preview --strictPort로 띄워 잰다(리뷰 11-07).
- 포트는
LAB_PERFORMANCE_PORT(기본 4173)다. 서버를 띄우기 전에 그 포트가 이미 응답하면 실패하고, 응답하는/release-manifest.json의 build·release가 로컬dist/release-manifest.json과 다르면 실패한다 (scripts/lib/lab-performance.ts,tests/unit/lab-performance.test.ts). - 새 브라우저 context에서
--runs=N(기본 5)번 재고, 예산은 중앙값으로 판정한다. 모든 측정값과 최소·최대는lab.json의context.sampling에 남는다. - named interaction은 페이지 안의 시계로 잰다. 클릭 이벤트의
timeStamp부터 대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고, lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry 길이(INP의 입력값)는context.sampling.clickEventDurationMs에 따로 남는다. - CPU 모델, 논리 CPU 수, 측정 전후 loadavg를
context.runner에 남긴다. - preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다.
corepack에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다.
2026-09-27 한 빌드를 10회 잰 결과(i5-10400F 12 CPU, loadavg 1117): 중앙값
LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction
10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은
빌드를 loadavg 79에서 다시 10회 재면 interaction 120148ms, LCP
1,9682,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라
뒤집히고, 중앙값 판정은 두 번 모두 통과였다.
The field minimum eligible-sample threshold is intentionally unresolved until
a privacy-approved telemetry baseline exists. Therefore the field command
fails closed with FAIL_UNVERIFIED when run against the example input. Provide
FIELD_WEB_VITALS_INPUT and MIN_ELIGIBLE_SAMPLES only after that decision is
recorded. The external input must identify a production release and an exact
28-day export window, name the source/export, carry privacy-approval and
threshold-decision references, and contain only non-negative route-ID samples.
The environment threshold must be a positive integer equal to the approved
decision embedded in the input. Invalid metadata fails as FAIL_UNVERIFIED;
the example can never serve as production evidence.
초기 청크 수와 HTTP/1.1
리뷰 1101/14.4. 08-08은 초기 JS 바이트를 줄이는 대신 초기 파일 수를 늘렸다
(vite.config.ts의 moduleSideEffects 주석). HTTP/1.1에서 브라우저는 한
호스트에 연결을 6개까지만 연다. 파일이 많으면 요청이 줄을 서서 왕복이 는다.
그래서 그때 빌드와 작은 초기 청크를 하나로 묶은 빌드를 쟀다(2026-11-03,
커밋 ec7435c). 아래 두 표의 파일 수와 바이트는 그 커밋의 값이다.
| 빌드 | 초기 JS 파일(entry 포함) | 초기 JS gzip(B) | 첫 화면까지 JS 요청 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---|---|---|---|---|
ec7435c |
26 | 202,782 | 27 | 5,887 ms | 1,874 ms |
(가) 08-08이 나눈 초기 primitive 청크 4개(field·button·select·page-templates)를 하나로 |
23 | 201,818 | 24 | 5,426 ms | 1,764 ms |
| (나) 묶을 수 있는 초기 청크 14개를 하나로 | 13 | 198,673 | 14 | 4,930 ms | 1,535 ms |
같은 빌드를 HTTP/2로 서빙하면(node:http2, 자체 서명 인증서, gzip) 차이가
거의 없다.
| 빌드 | Fast 3G 첫 화면 | Fast 4G 첫 화면 |
|---|---|---|
ec7435c |
4,793 ms | 1,444 ms |
| (가) | 4,769 ms | 1,440 ms |
| (나) | 4,708 ms | 1,422 ms |
측정 조건:
vite preview(HTTP/1.1, gzip 응답)로 띄우고 Chromium으로 잰다. 네트워크는 CDPNetwork.emulateNetworkConditions에 DevTools 프리셋 값을 넣었다. Fast 3G는 지연 562.5 ms·내려받기 180,000 B/s, Fast 4G는 165 ms·1,012,500 B/s다.- 매번 새 browser context에서 캐시 없이
/를 연다. 첫 화면은 boot 셸이 사라지고#main-content h1[data-route-heading]가 DOM에 들어온 시각이다 (performance.now()). - 세 빌드를 번갈아 7번씩 재고 중앙값을 적었다. 7번의 범위는
ec7435c5,8666,077 ms, (가) 5,3845,652 ms, (나) 4,8915,032 ms다(Fast 3G). loadavg는 HTTP/1.1 측정 때 620, HTTP/2 측정 때 3~6이었다. 그래서 두 표끼리는 비교하지 않는다. - CDP 지연은 요청마다 붙는다. 연결 수립(TCP·TLS) 비용은 따로 재지 않았다.
- (나)에서 묶지 않은 것: entry·
preload-helper·boot, 부트 실패 화면이 쓰는 모듈(render-boot-failure·react·react-dom·jsx-runtime·operation-id·diagnostics·boot-messages, 09-03), 15-01의feature-declarations·feature-platform.
판단: 지금은 묶지 않는다.
- HTTP/1.1에서는 묶는 편이 빠르다. Fast 3G에서 (가) 0.46초, (나) 0.96초 빨라지고 초기 JS도 조금 준다.
- 그러나 (가)·(나)는 이 빌드의 청크 안 모듈 목록을 그대로 적어 만들었다.
규칙으로 고르는 방법은 찾지 못했다.
- 모듈 그래프로 boot의 정적 closure를 따라가면 design-system 배럴을 지나 갤러리 전용 primitive까지 잡힌다. 그 primitive가 다시 초기 청크로 간다.
- rolldown의
$initial태그는 entry가 앱을 dynamic import로 읽어서(09-03) 아무것도 잡지 않는다. boot.tsx를 entry로 더하면 manifest 분류가 lazy 화면까지 초기로 센다 (28개, 216,820 B로 예산 초과).
- 고정 목록은 셸이 쓰는 primitive가 바뀔 때마다 다시 맞춰야 한다. 목록이
낡아도 실패하는 검사가 없다. 08-08이 같은 이유로
manualChunks이름 고정을 버렸다. - HTTP/2에서는 (나)도 Fast 3G 85 ms, Fast 4G 22 ms 차이다(위 둘째 표).
그래서 템플릿은 HTTP/2 이상으로 서빙한다고 본다. 초기 파일 수는
config/performance/budgets.json의 initialJsFiles가 막는다(1103/15-05). 상한은
템플릿 그대로의 수(26)에 6을 더한 32다. 기능의 지연 페이지가 셸과 같은 구성요소
(Button, SearchField 등)를 쓰면 그 구성요소가 별도 공유 청크로 떨어져 초기
파일이 하나 는다(1103 X2 #4). 상한을 현재 수와 같게 두면 그런 기능 하나로 게이트가
실패한다. HTTP/2에서 파일 하나는 거의 비용이 없다(위 표). 32를 넘으면 상한을 올리기
전에 vite.config.ts의 청크 그룹으로 공유 청크를 묶을지 본다. 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가 본다.