빌드와 패키징

src/의 React/TS 코드가 어떻게 dist/에 떨어지는지, import.meta.env의 VITE_* 노출 경계가 어디서 강제되는지, src/shared/config/env.ts의 zod 검증이 빌드 차단 게이트 역할을 하는 자리, 그리고 api/functions/가 별도 트랙으로 어떻게 배포되는지를 봅니다. architecture에서 잡은 FSD 트리가 여기서 번들과 만나 정적 호스팅 가능한 산출물이 됩니다.

두 트랙

graph LR
  src[src/ — Vite SPA]
  vite[vite build]
  dist[dist/]
  hosting[정적 호스팅]

  api[api/functions/]
  cli[supabase functions deploy]
  edge[Supabase Edge runtime]

  src --> vite --> dist --> hosting
  api --> cli --> edge

src/는 Vite가 번들합니다. pnpm build가 dist/를 떨굽니다. 그 자리를 Vercel, Netlify, Cloudflare Pages, self-host 중 한 곳에 정적 호스팅으로 올립니다.

api/functions/는 Vite와 무관합니다. supabase functions deploy <name>이 Deno 함수 한 개씩 Supabase 프로젝트에 올립니다. 빌드 산출물은 따로 떨어지지 않고 Supabase 쪽 인프라가 들고 있습니다.

두 트랙이 분리된 이유는 런타임이 다르기 때문입니다. SPA는 브라우저, Edge Function은 Deno. 같은 빌드 파이프라인에 묶으면 service_role 키가 SPA 번들에 새거나, 브라우저 API가 Deno 함수에 들어가는 사고가 생깁니다.

Vite SPA 빌드

pnpm build      # dist/ 에 production 빌드
pnpm preview    # dist/ 를 로컬에서 미리보기

pnpm build가 떨구는 dist/는 정적 파일 묶음입니다. index.html 하나, vendor chunk, route별 chunk, CSS 번들, 정적 자산. SPA라 entry point가 하나라 빌드 산출물도 단일 entry chunk + vendor chunk + route별 lazy chunk 모양입니다.

이 상태로 nginx, S3 + CloudFront, Vercel, Netlify 어디든 정적 호스팅이 되면 띄울 수 있습니다.

import.meta.env와 VITE_ 노출 경계

Vite의 환경변수 노출은 prefix가 결정합니다. VITE_로 시작하는 변수만 클라이언트 번들에 노출됩니다.

// 클라이언트에서 닿는 자리
import.meta.env.VITE_SUPABASE_URL          // ok
import.meta.env.VITE_SUPABASE_ANON_KEY     // ok
import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY // ok

// 클라이언트에서 undefined로 잡히는 자리
import.meta.env.SUPABASE_SERVICE_ROLE_KEY  // undefined
import.meta.env.STRIPE_SECRET_KEY          // undefined
import.meta.env.STRIPE_WEBHOOK_SECRET      // undefined

SUPABASE_SERVICE_ROLE_KEY 같은 서버 전용 시크릿이 실수로 클라이언트 코드에 들어가도 import.meta.env에서 undefined로 잡힙니다. 변수 이름의 prefix 자체가 노출 경계입니다.

대신 그 변수들이 정말로 필요한 자리(예: Edge Function 안)에서는 Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')로 닿습니다. Supabase가 Edge Function 배포 시 자기 인프라에서 그 환경변수를 자동 주입합니다.

env.ts zod 검증

src/shared/config/env.ts가 빌드 시작 시점에 zod로 환경변수를 검증합니다. 누락 시 빌드 즉시 실패합니다.

import { z } from 'zod';

const Env = z.object({
  VITE_SUPABASE_URL: z.string().url(),
  VITE_SUPABASE_ANON_KEY: z.string().min(20),
  VITE_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
  VITE_API_MODE: z.enum(['edge-functions', 'hono']).default('edge-functions'),
});

export const env = Env.parse(import.meta.env);

Env.parse(...)가 실행되는 시점은 번들의 어디서든 env를 처음 import 하는 자리입니다. 빌드 시점에 정적 평가가 닿지 않으면 런타임 첫 진입에 터집니다. 그 자리도 사용자 화면이 뜨기 전이라 운영 사고가 아니라 배포 실패로 잡힙니다.

startsWith('pk_')처럼 키의 prefix를 강제하는 자리가 들어가 있습니다. pk_test_ 또는 pk_live_로 시작하지 않는 값이 들어오면(예: 실수로 secret key를 넣었을 때) zod가 잡습니다. 같은 변수 이름에 잘못된 키가 들어가는 자리를 막아주는 안전망입니다.

route별 chunk size 목표

route별 chunk size는 200KB gzip 미만이 review-saas의 빌드 차원 5점 기준입니다. 초기 chunk가 500KB를 넘으면 3점으로 떨어집니다.

pnpm build가 콘솔에 chunk별 size를 출력합니다. 비대한 자리가 있으면 bundle analyzer로 어떤 의존성이 들어가 있는지 봅니다.

pnpm build
# 또는
pnpm dlx vite-bundle-visualizer

Vite 기본이 route별 code splitting을 자동으로 잡습니다. React.lazy로 페이지 컴포넌트를 import 하면 라우트 진입 시점에 chunk가 떨어집니다. 라우트 트리는 phase 5에서 자동 생성되며, lazy import 패턴이 그 자리에 박혀있습니다.

비대한 의존성이 자주 잡히는 자리는 셋입니다.

• 차트 라이브러리 (recharts, chart.js)를 marketing 페이지에 import. 대시보드 chunk에만 둡니다
• DOMPurify, marked 같은 sanitize/parser를 entry chunk에 import. lazy load
• Stripe SDK의 elements 패키지를 결제 페이지가 아닌 자리에 import. features/checkout 내부에서만

Edge Functions deploy

supabase functions deploy checkout-session
supabase functions deploy customer-portal
supabase functions deploy stripe-webhook

각 함수가 api/functions/<name>/index.ts 한 파일을 진입점으로 합니다. supabase functions deploy <name>이 그 디렉토리를 Deno bundle로 묶어 Supabase Edge runtime에 올립니다.

환경변수는 Supabase 대시보드 또는 CLI로 주입합니다.

supabase secrets set STRIPE_SECRET_KEY=sk_live_...
supabase secrets set STRIPE_WEBHOOK_SECRET=whsec_...
supabase secrets list

supabase secrets set은 Supabase 프로젝트에 비밀을 박는 자리고, 함수 안에서 Deno.env.get('STRIPE_SECRET_KEY')로 닿습니다. .env* 파일과 무관합니다.

로컬에서 Edge Function을 띄울 때는 다릅니다.

supabase functions serve --env-file ./api/functions/.env.local

로컬 .env.local이 .gitignore에 있어야 합니다. .env.example만 git에 박힙니다. 보안 기준선 S2 자리입니다.

환경변수 체크리스트

배포 직전에 확인할 자리.

변수	어디로	어디서
VITE_SUPABASE_URL	클라이언트 번들	호스팅(Vercel/Netlify/CF Pages) env
VITE_SUPABASE_ANON_KEY	클라이언트 번들	호스팅 env
VITE_STRIPE_PUBLISHABLE_KEY	클라이언트 번들	호스팅 env
VITE_API_MODE	클라이언트 번들 (어댑터 선택)	호스팅 env
SUPABASE_SERVICE_ROLE_KEY	Edge Function only	supabase secrets set
STRIPE_SECRET_KEY	Edge Function only	supabase secrets set
STRIPE_WEBHOOK_SECRET	Edge Function only (webhook 함수)	supabase secrets set

이 표가 distribution 자리의 4갈래 호스팅 안내로 이어집니다. 각 호스팅이 env를 어떻게 주입하는지가 거기서 갈립니다.

.env.example이 베이스에 박혀 있고, 본인 SaaS의 도메인별 추가 변수(예: 서드파티 API 키)는 phase 5의 /5-customize-saas 결과로 같은 파일에 append 됩니다. 이 자리는 fork 시 채워집니다.

자동화가 멈추는 자리

pnpm build가 dist/를 떨군 자리, supabase functions deploy가 함수를 올린 자리. 거기까지가 base 자동화의 끝입니다. 그 다음에 어느 호스팅에 올릴지, custom domain을 어떻게 잡을지, Stripe production webhook endpoint를 어디로 박을지는 도구가 손을 떼는 영역입니다.

deploy-saas 스킬이 dist/ 옆에 같이 떨구는 docs/deployment/DEPLOYMENT.md도 결정용 메모일 뿐, 자동으로 누군가에게 보내거나 어딘가로 올리지 않습니다.

이 경계는 의도된 것입니다. 호스팅 콘솔과 Stripe production 키와 DNS는 사용자 자격으로 행동해야 닿는 자리고, 자동화가 그 선을 넘으면 비밀이 새거나 production에 잘못된 webhook이 박힙니다. 다음 절에서 4갈래 호스팅과 Stripe production webhook 등록 절차를 봅니다.

다음

다음 섹션은 distribution입니다. Vercel, Netlify, Cloudflare Pages, self-host 4갈래의 트레이드오프, 각 자리에서 env 주입 명령, custom domain, CSP connect-src, 그리고 Stripe production webhook과 Supabase production 프로젝트 분리를 봅니다.