English {#english}
Cloudflare Pages Integration Plan
Doc version: 1.1. Plan for wiring Next.js (client-web) to Cloudflare (Pages, D1, R2, Vectorize, AI), local Wrangler testing, and GitHub → Pages deploy. Context: Prego pnpm monorepo, apps/client-web = Next.js (v0.dev). Dashboard: Settings > Build (build command, root, output), Variables and Secrets.
Full checklist, Edge runtime, build scripts, and local test guide are in the 한국어 section below.
flowchart LR A[wrangler.toml] --> B[Edge runtime] B --> C[pages:build] C --> D[pages:dev] D --> E[Deploy]
한국어 {#korean}
Cloudflare Pages 연동 기획서
문서 버전: 1.1
작성 목적: Next.js(client-web)와 Cloudflare 서비스 연동 및 로컬 Wrangler 테스트·자동 배포 환경 구축을 위한 기획 (코드 생성 전)
환경: Prego pnpm 모노레포, apps/client-web = v0.dev 기반 Next.js 앱
Cloudflare Pages 대시보드 메뉴 (확인된 위치)
- Settings > Build: 빌드 설정 (Build command, Root directory, Output directory 등).
- Variables and Secrets: 배포·프리뷰용 환경 변수 및 시크릿 설정.
1. 현황 요약
| 항목 | 내용 |
|---|---|
| 프로젝트 | Prego (pnpm 모노레포) |
| 앱 위치 | apps/client-web (Next.js, v0.dev 기반) |
| 로컬 | pnpm dev 등 Next.js 로컬 실행은 정상 동작 |
| 배포 | Cloudflare Pages 배포 시 실패 |
| 주요 에러 | No wrangler.toml file found, Build Command 실행 실패 (Failed: error occurred while running build command) |
2. 목표
- Cloudflare 서비스(Pages, Workers, R2, D1, Queues, Vectorize, AI)를 Next.js와 연동할 수 있는 기반 마련.
- 로컬 Wrangler 테스트 환경 구축으로, 배포 전에 D1/R2/Vectorize/AI 바인딩 및 Edge 런타임 동작을 검증.
- GitHub Push → Cloudflare Pages 자동 배포가 성공하도록 빌드 설정 및 대시보드 설정 정리.
3. 왜 이 과정이 중요한가
next build만 하는 것과 next-on-pages 빌드 후 wrangler로 실행하는 것은 다릅니다.- wrangler.toml이 있어야 코드에서
process.env.DB(D1),process.env.BUCKET(R2) 등 바인딩을 에러 없이 사용할 수 있습니다. - Vectorize & Workers AI는 Cloudflare Edge 런타임에서만 동작하므로, 로컬에서
wrangler pages dev로 테스트해야 배포 후 런타임 에러를 미리 잡을 수 있습니다.
4. 수행 요청 사항 (구현 체크리스트)
4.1 wrangler.toml 생성
| 항목 | 내용 |
|---|---|
| 위치 | apps/client-web/wrangler.toml (client-web 폴더 루트에 단일 파일로 생성) |
| 포함 설정 | Cloudflare Pages 프로젝트 설정, D1, R2, Vectorize 바인딩 (필요 시 AI 바인딩 추가) |
| compatibility_date | 설정 시점의 오늘 날짜 (예: 2026-02-12) — 구현 시 실제 날짜로 기입 |
| 참고 | Cloudflare Pages + Workers 설정, D1/R2/Vectorize 바인딩 |
설정 시 정의할 항목 (예시, 실제 이름은 팀 규칙에 따름)
- Pages:
name,compatibility_date - D1:
database_id,database_name(로컬/프리뷰용preview_database_id권장) - R2:
bucket_name - Vectorize:
index_name - (선택) AI: Workers AI 바인딩 (
binding이름, 예:AI)
wrangler.toml 작성 후
- 이 파일이 있으면 로컬에서
pnpm wrangler pages dev실행 시 위 바인딩이 Workers/Pages 런타임에 주입됩니다. - 다음 단계: 4.5 로컬 테스트 가이드에 따라 D1/R2/Vectorize를 참조하는 코드를 실제로 호출해 보며 검증합니다.
4.2 환경 설정 수정 (Edge Runtime 호환)
| 항목 | 내용 |
|---|---|
| 목적 | Cloudflare Edge Runtime에서 동작하도록 모든 페이지·라우트가 Edge를 사용하는지 확인 |
| 조치 | 다음 파일 최상단에 export const runtime = 'edge'; 가 있는지 점검하고, 누락된 파일에만 추가 |
점검 대상 (현재 구조 기준)
- page.tsx (12개)
app/page.tsxapp/signin/page.tsx,app/signup/page.tsxapp/checklist/page.tsx,app/checklist/add/page.tsxapp/expenses/page.tsx,app/expenses/capture/page.tsxapp/invoices/page.tsx,app/invoices/create/page.tsxapp/leaves/page.tsx,app/my-ai/page.tsx,app/notices/page.tsx
- route.ts
- 현재
apps/client-web내 route.ts 없음. 추후app/api/**/route.ts등 추가 시 동일하게 최상단에export const runtime = 'edge';점검·추가.
- 현재
주의
'use client'가 있는 페이지는 서버/엣지 설정이 레이아웃 등 서버 컴포넌트에 의해 결정될 수 있음. Next.js 문서 및 next-on-pages 가이드에 따라 페이지 단위 또는 레이아웃 단위로 Edge 지정 여부를 정리할 것.- Edge에서 사용 불가한 Node 전용 API가 있는 라우트는 제외하거나 별도 런타임 전략 수립.
4.3 빌드 스크립트 최적화
| 항목 | 내용 |
|---|---|
| 파일 | apps/client-web/package.json 의 scripts |
| 추가할 스크립트 | ① next-on-pages 빌드 ② wrangler 로컬 에뮬레이션(pages dev) |
추가 예시 (pnpm 기준)
next-on-pages빌드:- 예:
"pages:build": "npx @cloudflare/next-on-pages"또는 패키지 스크립트로next-on-pages실행하는 명령. - (next-on-pages 문서에 따라
next build를 래핑하는 형태일 수 있음 — 문서 확인 후 정확한 명령 기입)
- 예:
- Wrangler 로컬 에뮬레이션:
- 예:
"pages:dev": "wrangler pages dev"(wrangler.toml의pages_build_output_dir사용) - next-on-pages는 워커·정적 파일을
.vercel/output/static에 출력. 로컬/배포 모두 이 경로 사용.
- 예:
- compatibility_date는 wrangler.toml과 동일한 날짜로 통일 권장.
의존 관계
- 로컬에서 “빌드 후 에뮬레이션” 테스트:
pnpm pages:build→pnpm pages:dev순서로 실행. 반드시pages:build를 먼저 실행해야 하며,.vercel/output은 빌드로만 생성됨. 404 시docs/error/pages-dev-404-no-functions.md참고.
4.4 Cloudflare Pages 대시보드 가이드
| 항목 | 내용 |
|---|---|
| 목적 | Failed: error occurred while running build command 해결 |
| 메뉴 위치 | Cloudflare Pages 프로젝트 → Settings > Build (Build command, Root directory, Output directory 등), Variables and Secrets (환경 변수·시크릿) |
Build Command 권장 (pnpm 모노레포 기준)
- 옵션 A (프로젝트 루트가 모노레포 루트인 경우)
- Build command:
pnpm install && pnpm --filter <client-web-package-name> run pages:build
- 또는 워크스페이스에서 client-web만 빌드하도록 설정된 스크립트가 있다면 해당 스크립트 사용 (예:
pnpm install && pnpm -F client-web pages:build).
- Build command:
- 옵션 B (Pages 프로젝트가 apps/client-web을 루트로 두는 경우)
- Root directory:
apps/client-web - Build command:
pnpm install && pnpm run pages:build - (이 경우 Cloudflare가
apps/client-web에서만 pnpm을 실행하므로, 상위 모노레포와의 관계에 따라pnpm install이 워크스페이스 루트에서 실행될 수 있는지 대시보드 동작 확인 필요.)
- Root directory:
Output directory
- next-on-pages 사용 시 wrangler.toml에
pages_build_output_dir = ".vercel/output/static"설정. 로컬은pnpm pages:dev만 실행. - Environment variables
NODE_VERSION등 필요한 변수는 Settings > Variables and Secrets에서 설정.- pnpm 사용 시
ENABLE_EXPERIMENTAL_COREPACK=1또는 CI에 맞는 pnpm 활성화 방법 적용.
정리
- “최적의 명령어”는 **실제 Cloudflare 연결 저장소(루트 디렉터리)**에 따라 다름.
- 기획서 단계에서는 **“pnpm install + client-web의 pages:build 실행”**을 Build Command의 골자로 두고, 배포 시 루트가 모노레포인지 앱인지에 따라 위 옵션 중 하나를 선택해 문서화할 것.
4.4.1 Docs 사이트 (Astro) — Cloudflare Pages 빌드 설정
| 항목 | 내용 |
|---|---|
| 목적 | Prego 레포의 docs(Astro/Starlight)를 Cloudflare Pages에 배포할 때 astro: not found 방지 |
| 전제 | docs는 pnpm 워크스페이스에 포함되어 있음 (pnpm-workspace.yaml에 docs 추가). 루트에서 pnpm install 시 docs 의존성(astro 등)도 설치됨. |
권장 설정 (Pages 프로젝트가 “docs 사이트” 전용인 경우)
- Root directory:
docs - Build command:
pnpm run build(또는npm run build) - Build output directory:
dist
대안 (Root directory를 비우고 레포 루트 기준으로 빌드하는 경우)
- Root directory: (비움)
- Build command:
pnpm run build:docs - Build output directory:
docs/dist
(build:docs 스크립트는 모노레포 루트 package.json에 정의되어 있음: cd docs && pnpm install && pnpm run build.)
4.5 로컬 테스트 가이드 (D1·R2·Vectorize 참조 및 에뮬레이션)
| 항목 | 내용 |
|---|---|
| 목적 | pnpm wrangler pages dev 실행 시 wrangler.toml에 정의한 D1, R2, Vectorize를 로컬에서 참조·테스트하는 방법 정리 |
전제
apps/client-web/wrangler.toml이 존재하고, D1·R2·Vectorize 바인딩이 정의되어 있음.- next-on-pages 빌드 산출물이 준비되어 있음 (예:
pnpm pages:build완료). - 로컬 테스트는 client-web 디렉터리에서 수행 (
cd apps/client-web).
4.5.1 로컬 실행: pnpm wrangler pages dev 시 리소스 참조 방식
-
실행 명령 (pnpm 기준)
pnpm pages:dev(또는wrangler pages dev— wrangler.toml에서 디렉터리·플래그 읽음)- 또는 package.json에
pages:dev스크립트를 두었다면:pnpm pages:dev
-
동작
- Wrangler가
wrangler.toml을 읽어 D1 / R2 / Vectorize 바인딩을 로컬 Workers/Pages 런타임에 주입합니다. - Next.js( next-on-pages ) 앱에서는 Edge 런타임에서 실행되는 코드만 이 바인딩에 접근할 수 있습니다.
- Wrangler가
-
코드에서 리소스 참조 (Next.js + next-on-pages 기준)
- D1:
getRequestContext().env.<D1_BINDING_NAME>→ D1 데이터베이스 클라이언트. (예: binding 이름이DB이면getRequestContext().env.DB.) - R2:
getRequestContext().env.<R2_BINDING_NAME>→ R2 버킷 객체. (예: binding 이름이BUCKET이면getRequestContext().env.BUCKET.) - Vectorize:
getRequestContext().env.<VECTORIZE_BINDING_NAME>→ Vectorize 인덱스 클라이언트. (예: binding 이름이VECTORIZE이면getRequestContext().env.VECTORIZE.) - 위
getRequestContext()는@cloudflare/next-on-pages에서 제공하는 API이며, 서버/Edge에서만 호출 가능합니다. - wrangler.toml에 적은 바인딩 이름과 코드에서 사용하는 env 속성 이름이 일치해야 합니다.
- D1:
-
로컬에서 테스트하는 흐름
- wrangler.toml에 D1/R2/Vectorize 바인딩 작성.
- (선택) D1 로컬 DB 생성·스키마 적용 (아래 4.5.2).
pnpm pages:build후pnpm wrangler pages dev ...(또는pnpm pages:dev) 실행.- 브라우저/API로 해당 리소스를 사용하는 페이지·라우트를 호출해, D1 쿼리·R2 접근·Vectorize 검색 등이 에러 없이 동작하는지 확인.
4.5.2 D1 로컬 테스트
- 로컬 D1 DB 생성:
pnpm exec wrangler d1 create <database_name>- 생성 후 출력되는
database_id를 wrangler.toml의preview_database_id(또는 개발용database_id)에 넣습니다.
- 스키마/시드 적용:
pnpm exec wrangler d1 execute <database_name> --local --file=./path/to/schema.sql- (경로는 프로젝트 구조에 맞게 조정.)
pnpm wrangler pages dev실행 시- wrangler.toml에 정의된 D1 바인딩이 위 로컬 DB를 가리키면, 코드의
getRequestContext().env.<D1_BINDING_NAME>를 통해 로컬 D1을 참조해 테스트할 수 있습니다.
- wrangler.toml에 정의된 D1 바인딩이 위 로컬 DB를 가리키면, 코드의
4.5.3 R2 로컬 테스트
- wrangler.toml에 R2 bucket 바인딩이 있으면
pnpm wrangler pages dev시 로컬 모드에서 자동으로 로컬 스토리지로 에뮬레이션됩니다. - 코드에서는
getRequestContext().env.<R2_BINDING_NAME>로 버킷에 접근합니다. - 로컬 전용 bucket 이름을 쓰고 싶으면
[env.dev]등으로 환경별 설정을 분리할 수 있습니다.
4.5.4 Vectorize 로컬 테스트
- wrangler.toml에 Vectorize index 바인딩이 있으면,
pnpm wrangler pages dev실행 시 해당 바인딩 이름으로 env에 주입됩니다. - 코드에서는
getRequestContext().env.<VECTORIZE_BINDING_NAME>로 인덱스를 참조합니다. - 실제 벡터 인덱스는 Cloudflare에 있으므로, 로컬에서는 “바인딩이 잡히는지·호출이 실패하지 않는지”까지 검증하고, 완전한 검색 동작은 배포 후 또는 스텁으로 확인하는 방식을 권장합니다.
4.5.5 터미널 명령어 요약 (pnpm 기준)
| 목적 | 명령어 |
|---|---|
| 의존성 설치 | pnpm install |
| next-on-pages 빌드 | pnpm run pages:build (client-web에서) 또는 모노레포 루트에서 pnpm -F <client-web> run pages:build |
| 로컬 Pages + D1/R2/Vectorize 에뮬레이션 | pnpm pages:dev (반드시 pnpm pages:build 후 실행; wrangler.toml의 pages_build_output_dir 사용) |
| D1 로컬 DB 생성 | pnpm exec wrangler d1 create <database_name> |
| D1 로컬 스키마 실행 | pnpm exec wrangler d1 execute <database_name> --local --file=./path/to/schema.sql |
- 위 명령은 apps/client-web 디렉터리에서 실행하는 것을 전제로 하며,
compatibility-date는 wrangler.toml의compatibility_date와 맞춥니다.
5. 구현 순서 제안
- wrangler.toml 작성 (4.1) — D1/R2/Vectorize/AI 바인딩 초안 포함, compatibility_date = 오늘.
- Edge runtime 점검 (4.2) — 모든 page.tsx 및 향후 route.ts 상단
runtime = 'edge'확인·보완. - package.json scripts 추가 (4.3) —
pages:build,pages:dev. - 로컬 검증 —
pnpm pages:build→pnpm pages:dev로 D1/R2 등 바인딩 동작 확인. - Cloudflare Pages Build Command 및 Output directory 반영 (4.4) 후 GitHub Push로 자동 배포 테스트.
6. 참고 자료
- Cloudflare Next.js (Pages) Guide
- @cloudflare/next-on-pages
- Wrangler CLI - Pages
- D1 Local Development
- Workers AI
- Vectorize
7. 문서 이력
- 1.0: 초안 작성 (wrangler.toml, Edge 점검, 빌드 스크립트, 대시보드 Build Command, 로컬 테스트 가이드 정리).
- 1.1: Cloudflare Pages 메뉴 위치(Settings > Build, Variables and Secrets) 반영. wrangler.toml을 apps/client-web에 두고 D1/R2/Vectorize 바인딩 작성 후 로컬 테스트로 이어지는 흐름 명시.
pnpm wrangler pages dev실행 시 D1/R2/Vectorize를 코드에서 참조하는 방법(getRequestContext().env) 및 로컬 테스트 가이드 보강.