KO/EN
문서

deployment

CF Pages 설정

Cloudflare Pages 프로젝트 생성과 GitHub 연동

CF Pages 설정

Modfolio 생태계의 모든 앱은 Cloudflare Pages에 배포됩니다. 이 문서에서는 프로젝트 생성부터 빌드 설정까지 전 과정을 다룹니다.

프로젝트 생성

Cloudflare Dashboard에서 Pages 프로젝트를 생성합니다.

  1. Workers & Pages → Create → Pages 탭 선택
  2. Connect to Git 선택 → GitHub 계정 연동
  3. 레포지토리 선택 (modfolio/<앱 이름>)
  4. Begin setup 클릭

주의: GitHub 연동은 프로젝트 생성 시에만 설정할 수 있습니다. 이미 Direct Upload로 생성한 프로젝트는 GitHub 연동으로 전환할 수 없습니다. 연동이 필요하면 프로젝트를 삭제 후 재생성해야 합니다.

Production 브랜치 설정

프로젝트 생성 시 Production 브랜치를 지정합니다.

설정 값
Production branch main
Preview branches main 외 모든 브랜치 (자동)

Preview 배포는 main이 아닌 브랜치에 push할 때마다 자동으로 생성됩니다. Preview URL 형식은 <commit-hash>.<project-name>.pages.dev입니다.

빌드 설정

프로젝트 생성 화면의 Build settings 섹션에서 빌드 명령어와 출력 디렉토리를 설정합니다.

프레임워크별 빌드 설정

프레임워크 Build command Build output directory
Astro bun run build apps/landing/dist
SvelteKit 5 bun run build .svelte-kit/cloudflare
SolidStart bun run build .output
Nuxt 3 bun run build .output/public
Qwik bun run build dist
Hono bun run build dist

Astro 프로젝트의 경우 @astrojs/cloudflare 어댑터가 설치되어 있어야 합니다.

bun add @astrojs/cloudflare
// astro.config.mjs
import cloudflare from "@astrojs/cloudflare";
import { defineConfig } from "astro/config";

export default defineConfig({
  adapter: cloudflare(),
  output: "server",
});

Node.js 버전 설정

Cloudflare Pages 빌드 환경의 기본 Node.js 버전은 오래된 LTS입니다. 최신 버전이 필요한 경우 환경변수로 지정합니다.

환경변수 값 설명
NODE_VERSION 20 Node.js 20.x LTS 사용

Dashboard에서 설정하는 경로:

Settings → Environment variables → Production (또는 Preview)
→ Add variable → NODE_VERSION = 20

참고: Modfolio 생태계는 런타임으로 Bun을 사용하지만, CF Pages 빌드 환경에서는 Node.js가 기본 런타임입니다. Bun을 빌드에 사용하려면 빌드 명령어 앞에 npx bun을 붙이거나, 빌드 이미지에 Bun이 설치된 환경을 확인하세요.

모노레포 루트 디렉토리 설정

Modfolio의 일부 앱은 모노레포 구조를 사용합니다. CF Pages에서 모노레포의 특정 앱을 빌드하려면 Root directory 설정이 필요합니다.

Settings → Build & deployments → Root directory

예를 들어 apps/landing에 Astro 프로젝트가 있는 모노레포의 경우:

설정 값
Root directory / (모노레포 루트)
Build command bun run build --filter=apps/landing
Build output directory apps/landing/dist

또는 Root directory 자체를 서브디렉토리로 지정할 수 있습니다.

설정 값
Root directory apps/landing
Build command bun run build
Build output directory dist

주의: Build output directory는 Root directory에 대한 상대 경로입니다. Root directory를 apps/landing으로 설정했다면, 출력 디렉토리는 dist만 입력하면 됩니다.

빌드 캐시

CF Pages는 node_modules를 자동으로 캐시합니다. 캐시를 무효화하려면 Dashboard에서 빌드를 재실행하면서 Clear cache and retry 옵션을 선택합니다.

의존성 설치 명령어를 명시하지 않으면 package-lock.json이 있으면 npm install, yarn.lock이 있으면 yarn install이 실행됩니다. bun.lockb가 있으면 Bun이 자동 감지됩니다.

다음 단계

ESC

검색어를 입력하세요