사이드 프로젝트를 빠르게 배포하고 싶을 때 Cloudflare Pages가 좋다. 무료 플랜으로도 충분하고, 글로벌 CDN이 기본이라 속도도 빠르다. Vercel이나 Netlify도 좋지만, 이미 Cloudflare를 쓰고 있다면 한 곳에서 관리하는 게 편하다. Git 연동 없이 CLI로 바로 배포하는 방법을 정리한다.

프로젝트 생성

Vite로 React 프로젝트를 만든다:

npm create vite@latest my-app -- --template react
cd my-app
npm install

TypeScript를 쓰고 싶으면 --template react-ts로 바꾸면 된다. 개발 서버를 띄워서 확인:

npm run dev

http://localhost:5173에서 기본 화면이 뜨면 정상이다.

빌드

배포 전에 빌드부터:

npm run build

dist/ 폴더에 빌드 결과물이 생긴다. 이 폴더를 그대로 Cloudflare Pages에 올리면 끝이다.

로컬에서 빌드 결과를 미리 확인하고 싶으면:

npm run preview

Wrangler로 배포

Cloudflare의 CLI 도구인 Wrangler를 설치한다:

npm install -g wrangler
wrangler login

브라우저가 열리면서 Cloudflare 계정 인증을 한다. 그 다음 배포:

npx wrangler pages deploy dist --project-name=my-app

처음 실행하면 프로젝트를 새로 만들겠냐고 물어본다. ‘y’를 누르면 프로젝트가 생성되면서 바로 배포된다. 배포가 완료되면 URL을 알려준다:

✨ Deployment complete!
https://abc123.my-app.pages.dev

이후 업데이트할 때도 같은 명령어를 치면 된다.

커스텀 도메인 연결

Cloudflare Dashboard → Pages → 프로젝트 → Custom domains에서 도메인을 추가한다. 도메인이 이미 Cloudflare DNS에 등록되어 있으면 자동으로 CNAME이 설정된다. SSL도 자동.

환경변수 설정

API 키 같은 걸 소스코드에 넣으면 안 된다. Vite에서 환경변수를 쓰려면 .env 파일에:

VITE_API_URL=https://api.example.com
VITE_APP_NAME=MyApp

코드에서는 import.meta.env.VITE_API_URL로 접근한다. VITE_ 접두사가 붙은 것만 클라이언트에 노출되니 주의.

빌드 시점에 환경변수를 주입할 수도 있다:

VITE_API_URL=https://api.example.com npm run build

SPA 라우팅 문제 해결

React Router를 쓸 때 /about 같은 경로로 직접 접속하면 404가 뜬다. 정적 호스팅에서는 서버가 그 경로에 파일이 없다고 판단하기 때문이다. public/_redirects 파일을 만들면 해결된다:

/* /index.html 200

모든 경로를 index.html로 보내서 React Router가 처리하게 한다. Cloudflare Pages는 _redirects 파일을 자동으로 인식한다.

또는 public/_headers 파일로 캐시 정책을 설정할 수도 있다:

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/index.html
  Cache-Control: no-cache

빌드된 JS/CSS 파일은 파일명에 해시가 포함되어 있으니 오래 캐싱해도 되고, index.html은 항상 최신을 받도록 한다.

배포 스크립트

매번 명령어 치기 귀찮으니까 package.json에 스크립트를 추가한다:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "deploy": "vite build && npx wrangler pages deploy dist --project-name=my-app --branch=main"
  }
}

이제 npm run deploy 한 줄이면 빌드부터 배포까지 끝난다. CI/CD를 구축할 필요 없이 로컬에서 바로 배포할 수 있어서 사이드 프로젝트에 딱이다.

Git 연동을 원하면 Cloudflare Pages 대시보드에서 GitHub/GitLab 저장소를 연결하면 push할 때마다 자동 배포도 가능하다. 하지만 빠르게 올리고 싶을 때는 CLI 배포가 더 간편하다.