Files
clean-architecture-frontend…/vite.config.ts
T
DongHyeonka c15345cb1d fix(dev): dev server가 설치된 기능의 contract set으로 release manifest를 낸다
문제
`create:feature`가 만든 기능은 계약 패키지(`@org-contracts/<base>`)를
선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을
그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이
집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가
CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를
보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의
test:browser-capabilities가 38건 실패하고("Execution context was
destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을
더하는 재실험(리뷰 조치 X2 #3)에서 찾았다.

고른 방법
- dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를
  시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려
  src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고,
  `/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에
  설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다.
- 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을
  import해야 하는데, Vite 설정이 그것을 불러오면 안 된다.
- build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다.
- 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가
  contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을
  다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다.

위험·한계
- dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다.
- 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다).

검증
- tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로
  바꾼다, 템플릿 그대로면 자리표시자와 같다).
- check:types, lint, check:architecture, check:ci 통과.
- 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3
2026-11-05 01:33:38 +09:00

258 lines
11 KiB
TypeScript

import { existsSync } from "node:fs";
import { createRequire } from "node:module";
import path from "node:path";
import { defineConfig, loadEnv } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import { devReleaseManifestPlugin } from "./scripts/lib/dev-release-manifest.ts";
import { viteModuleInventoryPlugin } from "./scripts/lib/vite-module-inventory.ts";
import { ENV_REGISTRY } from "./src/contracts/env.ts";
/**
* 13-06. Every VITE_* value Vite loads (shell or `.env*`) is public once
* something bundles it, so a value the build does not declare is refused
* rather than carried along.
*/
function assertDeclaredBuildVariables(mode: string): void {
const undeclared = Object.keys(loadEnv(mode, process.cwd(), "VITE_"))
.filter((name) => !Object.hasOwn(ENV_REGISTRY, name))
.sort();
if (undeclared.length > 0) {
throw new Error(
`Undeclared VITE_* build variables: ${undeclared.join(", ")}. ` +
"Declare them in ENV_REGISTRY (src/contracts/env.ts) or unset them; " +
"VITE_ values are published to the browser.",
);
}
}
/**
* §6.1. One sub-path, declared once.
*
* `VITE_ROUTER_BASE_PATH` already drives the router and the Service Worker
* scope. Vite's asset `base` was left at its default, so a build served from
* `/app/` emitted root-absolute asset URLs and loaded nothing: the three
* consumers of the same setting disagreed. They are read from one value here so
* a sub-path deployment is coherent or fails at build time.
*/
function routerBasePath(environment: NodeJS.ProcessEnv): string {
const declared = environment["VITE_ROUTER_BASE_PATH"];
if (declared === undefined || declared === "") return "/";
if (!declared.startsWith("/") || !declared.endsWith("/")) {
throw new Error(
`VITE_ROUTER_BASE_PATH must start and end with "/"; received ${declared}`,
);
}
return declared;
}
/**
* 13-07. The runtime document ships inside dist, which is served under the
* base path. An explicit root-relative URL outside it would 404 at boot.
*/
function assertRuntimeConfigUnderBase(
environment: NodeJS.ProcessEnv,
base: string,
): void {
const declared = environment["VITE_RUNTIME_CONFIG_URL"];
if (declared?.startsWith("/") && !declared.startsWith(base)) {
throw new Error(
`VITE_RUNTIME_CONFIG_URL ${declared} is outside VITE_ROUTER_BASE_PATH ${base}`,
);
}
}
type ModuleGraph = Readonly<{
getModuleInfo(id: string): Readonly<{
importedIds: readonly string[];
dynamicallyImportedIds: readonly string[];
}> | null;
}>;
function staticClosure(
graph: ModuleGraph,
roots: readonly string[],
within: (id: string) => boolean = () => true,
): Set<string> {
const reached = new Set<string>();
const pending = [...roots];
for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
if (reached.has(next) || !within(next)) continue;
reached.add(next);
pending.push(...(graph.getModuleInfo(next)?.importedIds ?? []));
}
return reached;
}
/**
* 15-01. Two chunk groups that keep moving the feature runtime halves out of
* the initial JavaScript from costing more than it saves.
*
* - `feature-declarations`: every installed feature's declaration, the static
* graph under src/features/ that the generated feature index reaches
* (feature-module.ts, its route contract and messages). A declaration is
* shared by the boot graph and its own feature's lazy runtime and pages,
* and rolldown otherwise gives each such set of importers a chunk of its
* own: one more initial file per feature, which doubled what a feature
* added to the initial JavaScript.
* - `feature-platform`: the boot modules the runtime halves also import (HTTP
* executor, contract runtime, zod). Left to rolldown they split into one
* initial chunk per set of importers; the per-file gzip overhead and the
* compression lost across files cost more than the runtime code removed.
* Modules that the boot-failure screen needs are left out, so
* render-boot-failure.tsx never depends on this chunk: it must still render
* when a module of the application graph throws while evaluating (09-03).
*
* Both only regroup modules the boot already loads; nothing lazy becomes
* initial. If feature-declarations comes out empty, the per-feature bound in
* tests/unit/feature-shape-growth.test.ts fails. feature-platform only moves
* the platform total (about 2 KB at 15-01), which the bundle budget
* (FE-GATE-012) checks.
*/
function createFeatureChunkGroups(root: string) {
const at = (file: string) => path.join(root, file);
const featuresRoot = `${at("src/features")}${path.sep}`;
let groups: ReadonlyMap<string, string> | undefined;
const classify = (graph: ModuleGraph): ReadonlyMap<string, string> => {
const index = graph.getModuleInfo(at("src/.generated/product-feature-index.ts"));
const declarations = staticClosure(graph, index?.importedIds ?? [], (id) =>
id.startsWith(featuresRoot),
);
const runtimes = staticClosure(
graph,
[...declarations].flatMap((id) => graph.getModuleInfo(id)?.dynamicallyImportedIds ?? []),
);
const boot = staticClosure(graph, [at("src/bootstrap/boot.tsx")]);
const bootFailure = staticClosure(graph, [at("src/bootstrap/render-boot-failure.tsx")]);
const result = new Map<string, string>();
for (const id of declarations) result.set(id, "feature-declarations");
for (const id of runtimes) {
if (boot.has(id) && !bootFailure.has(id) && !declarations.has(id)) {
result.set(id, "feature-platform");
}
}
return result;
};
return (id: string, graph: ModuleGraph): string | null => {
groups ??= classify(graph);
return groups.get(id) ?? null;
};
}
/**
* 1103/15-07. react-router publishes its production build under
* dist/production, but its exports map points every condition at
* dist/development. A production bundle carried the router's development
* warnings (ENABLE_DEV_WARNINGS): 604 gzip bytes of initial JavaScript at
* 15-07 and warnings in the production console. A build resolves the two
* entries react-router-dom imports to the production files next to the
* development entry. If an upgrade moves them, the build stops here rather
* than silently shipping the development build again;
* tests/unit/build-environment-bundle.test.ts checks the bundle. Remove this
* when the package exports a production condition.
*/
function reactRouterProductionAliases(root: string) {
const projectRequire = createRequire(path.join(root, "package.json"));
const routerRequire = createRequire(projectRequire.resolve("react-router-dom"));
const production = path.join(path.dirname(routerRequire.resolve("react-router")), "..", "production");
const aliases = [
{ find: /^react-router$/u, replacement: path.join(production, "index.mjs") },
{ find: /^react-router\/dom$/u, replacement: path.join(production, "dom-export.mjs") },
];
const missing = aliases.filter(({ replacement }) => !existsSync(replacement));
if (missing.length > 0) {
throw new Error(
`react-router production build not found: ${missing.map(({ replacement }) => replacement).join(", ")}`,
);
}
return aliases;
}
export default defineConfig(({ command, mode }) => {
assertDeclaredBuildVariables(mode);
const base = routerBasePath(process.env);
assertRuntimeConfigUnderBase(process.env, base);
return {
base,
plugins: [react(), tailwindcss(), viteModuleInventoryPlugin(), devReleaseManifestPlugin()],
// Development keeps the router's warnings.
resolve: command === "build" ? { alias: reactRouterProductionAliases(process.cwd()) } : {},
build: {
manifest: true,
sourcemap: false,
rolldownOptions: {
/**
* 1101/08-08. The design-system modules have no top-level effects:
* they declare components, icons and token lists. Declared so, a
* primitive file none of whose exports a chunk uses is dropped from
* it, instead of riding the initial chunk because the app shell
* imports the index that re-exports it. The bundler drops an import
* kept only for its effect along with its module, so these files hold
* no such import; tests/unit/design-system-initial-chunk.test.ts
* checks both. Stylesheets load from bootstrap/main.tsx.
*
* Trade: at 08-08 the initial JavaScript fell by 2,718 gzip bytes
* and the initial chunks rose from 16 to 25. The entry preloads them
* in parallel, so over HTTP/2 they add no round trip. Over HTTP/1.1
* they queue for six connections; 1101/14.4 measured that cost and
* why the chunks stay split ("초기 청크 수와 HTTP/1.1" in
* docs/operations/performance-evidence.md).
*/
treeshake: {
moduleSideEffects: [
{
test: /[\\/]src[\\/]presentation[\\/]design-system[\\/].+\.tsx?$/,
sideEffects: false,
},
],
},
output: {
codeSplitting: {
groups: [
// 09-03. The entry now imports the app dynamically, so Vite's
// preload helper would land in the entry chunk and every lazy
// 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
// import then preloads one more file (about 50 gzip bytes of
// initial JavaScript for the second feature). Those imports
// already preload schema-registry.ts, so the adapter rides
// that lazy chunk. Both modules stay off the boot graph.
{
name: "schema-registry",
test: /[\\/]src[\\/]contracts[\\/](?:schema-registry|zod-validator)\.ts$/,
includeDependenciesRecursively: false,
},
{
name: createFeatureChunkGroups(process.cwd()),
// The boot-failure screen's modules stay out of
// feature-platform even when a grouped module imports them.
includeDependenciesRecursively: false,
},
],
},
},
},
},
};
});