frontend-build

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 처럼 네이티브 바이너리를 내려받는 패키지는 명시 허용이 필요하다.

// 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

반드시 확인하는 설정

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { "@": path.resolve(import.meta.dirname, "./src") } },
  build: {
    outDir: "dist",
    sourcemap: false,   // 배포본에 원본 코드를 싣지 않는다
    emptyOutDir: true,  // §4 에 해당하면 false
  },
  server: { proxy: { "/api": "http://localhost:9992" } },
})

• sourcemap: false — 켜두면 배포 산출물에서 원본을 복원할 수 있다. 폐쇄망·사내 도구라도 기본은 끈다. 필요하면 별도 아티팩트로 빼고 배포물에는 넣지 않는다.
• server.proxy — 개발 중 백엔드로 넘길 경로. 이걸 안 두면 CORS 를 열게 되고, 그 설정이 운영까지 따라간다.
• 환경변수는 VITE_ 접두사만 클라이언트에 노출된다. 접두사 없는 값은 번들에 안 들어가고, 반대로 접두사를 붙이는 순간 공개된다 — 비밀을 넣지 않는다.
• 하위 경로 배포면 base 를 지정한다. 안 하면 자산 경로가 루트 기준으로 깨진다.