frontend-buildlisted

# frontend-build 빌드·패키징 층을 담당한다. 컴포넌트 코드는 `react-expert` 가 맡는다. 이 문서는 **모델이 이미 아는 일반론을 적지 않는다.** 버전별 함정, 실측으로 확인한 사실, doksam 고유 규약, 그리고 판단이 갈리는 지점만 담는다. ## 0. 먼저 확정할 것 1. **산출물이 어디로 가는가** — 정적 호스팅 / 다른 언어 바이너리에 내장(`go:embed` 등) / 컨테이너. 내장이면 §4 를 반드시 읽는다. 뒤늦게 바꾸면 `.gitignore` 와 빌드 순서가 전부 얽힌다. 2. **폐쇄망인가** — 그렇다면 외부 CDN·폰트·원격 이미지가 0건이어야 한다(§3). 3. **패키지 매니저** — 레포에 이미 있는 락파일을 따른다. 섞지 않는다(§1). ## 1. pnpm ### 락파일이 곧 계약이다 - 설치는 CI·재현 환경에서 **`pnpm install --frozen-lockfile`**. 락파일이 어긋나면 조용히 올려버리는 대신 실패해야 한다. - 락파일을 지우고 다시 만드는 것은 "고치는" 게 아니라 **의존성 트리 전체를 바꾸는 변경**이다. 원인 파악 없이 삭제·재생성하지 않는다. - `package.json` 과 락파일은 **항상 같은 커밋**에 들어간다. ### lifecycle 스크립트는 기본 차단이다 pnpm 10부터 의존성의 install 스크립트가 기본으로 실행되지 않는다. `esbuild`·`sharp` 처럼 네이티브 바이너리를 내려받는 패키지는 **명시 허용**이 필요하다. ```jsonc // package.json "pnpm": { "onlyBuiltDependencies": ["esbuild", "sharp"] } ``` 증상이 "빌드는 되는데 런타임에 바이너리가 없다"로 나타나므로, 이 계열 오류를 보면 설치 로그의 차단 경고부터 확인한다. **아무거나 허용 목록에 넣지 않는다** — 임의 코드 실행이다. ### 워크스페이스 - `pnpm-workspace.yaml` 이 패키지 경계다. 루트에는 도구만 두고 앱 의존성을 올리지 않는다. - 패키지 간 참조는 `"workspace:*"`. 버전 번호를 손으로 맞추지 않는다. - 특정 패키지에서 실행: `pnpm --filter <pkg> build`. 루트에서 `cd` 로 들어가지 않는다. - 버전을 강제로 맞춰야 하면 `pnpm.overrides`. 단 **왜 필요한지 주석**을 남긴다. 근거 없는 override 는 다음 업그레이드에서 아무도 못 지운다. ### npx / dlx 일회성 CLI 는 `pnpm dlx <pkg>`. `npx` 는 npm 계열 캐시를 따로 쓰므로 pnpm 레포에서 섞으면 버전이 갈린다. 다만 **shadcn CLI 처럼 `npx` 를 전제로 문서화된 도구**는 그대로 써도 된다 — 설치가 아니라 코드 생성이 목적이라 트리에 영향이 없다. ## 2. Vite ### 반드시 확인하는 설정 ```ts export default define