Communitygithub.com

bighadj22/codflow

CodFlow 스토어프론트(cod-astro/theme01)를 Vercel에 배포 또는 재배포합니다. AI 에이전트가 Vercel 프로젝트를 구성하고(DEPLOY_TARGET=vercel), 환경 변수(COD_SERVER_URL, STORE_API_KEY, MEDIA_DOMAIN)를 바인딩하며, Vercel CLI 또는 Git 통합을 통해 빌드 및 배포하고, 스토어프론트 기능을 확인합니다. 개발자가 스토어프론트를 Vercel에 배포하거나, Cloudflare Workers에서 Vercel로 전환하거나, Vercel 스토어프론트 배포 문제를 해결해야 할 때 사용합니다.

codflow란 무엇인가요?

이 스킬은 CodFlow의 고객 대상 스토어프론트 테마(`cod-astro/theme01`)를 Vercel에 배포하는 과정을 자동화합니다. CodFlow 백엔드(`cod-server`)와 관리자 대시보드(`cod-client-astro`)는 Cloudflare Workers에서 실행되지만, 스토어프론트는 `DEPLOY_TARGET=vercel` 설정을 통해 Vercel에 배포할 수 있습니다. Vercel 배포는 Cloudflare의 Error 1042(Worker-to-Worker 차단) 문제를 해결하고, 넉넉한 글로벌 엣지 대역폭과 자동 미리보기 배포 기능을 제공합니다. 이 스킬은 Vercel CLI를 통한 터미널 기반 배포와 Vercel Dashboard/Git 통합을 통한 지속적 배포 두 가지 방법을 모두 지원합니다. 필수 환경 변수(`COD_SERVER_URL`, `STORE_API_KEY`, `MEDIA_DOMAIN`) 설정, 프로덕션 배포 실행, 라이브 URL에 대한 스모크 테스트를 포함한 전체 워크플로우를 안내합니다. 또한 사용자 정의 도메인 설정 및 일반적인 문제 해결 방법도 제공합니다. AI 에이전트 또는 개발자는 이 스킬을 사용하여 스토어프론트를 안정적으로 Vercel에 배포하고, Cloudflare Workers에서 전환하거나 기존 Vercel 배포 문제를 진단할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bighadj22/codflow/tree/HEAD/.agents/skills/storefront-vercel
원본 보기→모든 스킬 둘러보기

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

문서

CodFlow 스토어프론트 — Vercel 배포 실행 가이드

cod-astro/theme01은 CodFlow(Astro 7)를 위한 고객 대상 스토어프론트 테마입니다. CodFlow 백엔드(cod-server)와 관리자 대시보드(cod-client-astro)는 Cloudflare Workers(D1, R2, KV 사용)에서 실행되는 반면, 스토어프론트는 동적 배포 대상을 지원합니다(DEPLOY_TARGET=vercel 또는 DEPLOY_TARGET=cloudflare).

스토어프론트를 Vercel에 배포하는 것은 종종 선호되는데, 그 이유는 다음과 같습니다.

  1. Cloudflare Error 1042 (Worker-to-Worker 차단) 해결: cod-server가 사용자 정의 도메인 없이 무료 *.workers.dev 하위 도메인에 배포된 경우, Cloudflare는 다른 Cloudflare Worker가 *.workers.dev에서 이를 가져오는 것을 차단합니다. Vercel은 Cloudflare의 내부 네트워크 외부에서 실행되므로, 사용자 정의 도메인 없이도 스토어프론트가 *.workers.dev의 cod-server를 가져올 수 있습니다.
  2. 넉넉한 글로벌 엣지 대역폭: Vercel은 스토어프론트 트래픽에 대해 넉넉한 대역폭과 엣지 CDN 캐싱을 제공합니다.
  3. 자동 미리보기 배포: 모든 Git 브랜치/PR은 테마 변경 사항을 테스트하기 위한 자체 미리보기 URL을 가질 수 있습니다.

필수 환경 변수

배포하기 전에 다음 값을 수집하세요:

변수설명예시
DEPLOY_TARGET필수. astro.config.mjs가 @astrojs/vercel을 사용하도록 지시합니다vercel
COD_SERVER_URL필수. 배포된 cod-server API의 기본 URLhttps://api.yourdomain.com 또는 https://codflow-server.<account>.workers.dev
STORE_API_KEY필수. D1에 시드된 키와 일치하는 원시 스토어 API 키codflow-setup 4단계에서 생성
MEDIA_DOMAIN선택 사항. R2 이미지 CDN을 위한 사용자 정의 도메인media.yourdomain.com

[!IMPORTANT] STORE_API_KEY는 비밀 정보입니다. SSR 라우트 및 API 프록시에서 서버 측에서 사용됩니다. 클라이언트 측 번들에 절대 노출하지 마십시오.

배포 방법

자동화/터미널 배포에는 방법 1 (Vercel CLI) 을, GitHub에서 지속적 배포에는 방법 2 (Vercel Dashboard / Git) 를 선택하세요.

방법 1: Vercel CLI를 통한 배포 (AI 에이전트에 권장)

1. 사전 조건

  • Vercel CLI가 npx vercel을 통해 접근 가능한지(또는 전역 설치) 확인하세요.
  • 인증 상태를 확인하세요: 
    npx vercel whoami
    로그인되지 않은 경우:
    • 브라우저 사용 가능: npx vercel login
    • 헤드리스/CI 환경: 환경에 VERCEL_TOKEN 설정 (export VERCEL_TOKEN="<token>").

2. 프로젝트 구성 및 연결

스토어프론트 디렉토리로 이동:

cd cod-astro/theme01

초기 설정 실행:

npx vercel link

대화형 프롬프트를 따르십시오(비대화형 세션의 경우 플래그 제공 가능):

  • 기존 프로젝트에 연결? No (또는 기존 연결 시 Yes)
  • 프로젝트 이름: <project>-storefront (예: mystore-storefront)
  • 코드가 있는 디렉토리는? ./

3. 환경 변수 설정

CLI를 사용하여 필수 프로덕션 환경 변수를 추가하세요:

# 1. 배포 대상
printf "vercel" | npx vercel env add DEPLOY_TARGET production

# 2. 백엔드 API URL (https://로 시작해야 함)
printf "https://<your-cod-server-domain>" | npx vercel env add COD_SERVER_URL production

# 3. 스토어 API 키
printf "<your-raw-store-api-key>" | npx vercel env add STORE_API_KEY production

# 4. 선택 사항: 미디어 도메인 (R2 사용자 정의 도메인이 구성된 경우)
printf "<media.yourdomain.com>" | npx vercel env add MEDIA_DOMAIN production

(선택 사항: 미리보기 브랜치를 사용할 계획이라면 preview 및 development 환경에도 추가하세요).

4. 프로덕션 빌드 및 배포

Vercel 어댑터를 사용하여 프로덕션 배포를 실행하세요:

cd cod-astro/theme01
npx vercel --prod

Vercel은 프로젝트를 업로드하고, npm run build:vercel(또는 DEPLOY_TARGET=vercel로 astro build)을 실행하고, SSR 서버리스/엣지 함수를 컴파일한 후, 라이브 프로덕션 URL(예: https://<project>-storefront.vercel.app)을 제공합니다.

방법 2: Vercel Dashboard를 통한 배포 (Git 통합)

GitHub / GitLab / Bitbucket 리포지토리를 연결할 때 이 방법을 사용하세요:

  1. Vercel에서 리포지토리 가져오기:

    • Vercel Dashboard에서 Add New... → Project를 클릭합니다.
    • codflow-os 리포지토리를 선택합니다.

  2. 프로젝트 설정 구성:

    • 프로젝트 이름: 예: codflow-storefront
    • 프레임워크 사전 설정: Astro
    • 루트 디렉토리: Edit을 클릭하고 cod-astro/theme01을 선택합니다. "빌드 단계에 루트 디렉토리 외부의 소스 파일 포함" 옵션을 선택합니다(워크스페이스 종속성이 루트 node_modules로 확인되므로 필요함).
    • 빌드 명령: Override를 토글하고 다음을 설정합니다: 
      npm run build:vercel
      (또는 환경 변수에 DEPLOY_TARGET=vercel이 설정된 경우 기본 astro build를 그대로 둡니다).
    • 출력 디렉토리: 기본값 유지 (.vercel/output).
    • 설치 명령: 기본값 유지 (npm install / 루트 워크스페이스 설치).

  3. 환경 변수 구성: 환경 변수 아래에 다음을 추가합니다:

    • DEPLOY_TARGET = vercel
    • COD_SERVER_URL = https://<your-cod-server-domain>
    • STORE_API_KEY = <your-raw-store-api-key>
    • MEDIA_DOMAIN = <media.yourdomain.com> (선택 사항)

  4. 배포:

    • Deploy를 클릭합니다. Vercel은 워크스페이스를 빌드하고, @astrojs/vercel로 Astro 사이트를 번들링한 후, 프로덕션 URL을 할당합니다.

확인 및 스모크 테스트

배포가 완료되면 라이브 Vercel URL에 대해 다음 검사를 실행하세요:

대상테스트 명령 / 작업예상 결과
홈페이지curl -s -o /dev/null -w "%{http_code}" https://<storefront-url>200 (HTML 응답)
카탈로그 SSR브라우저에서 https://<storefront-url>/ 열기제품이 이미지, 가격, 제목과 함께 로드됨
제품 상세브라우저에서 https://<storefront-url>/product/<slug> 열기제품 페이지가 체크아웃/주문 양식과 함께 렌더링됨
장바구니 / 주문 흐름테스트 주문 제출 (또는 테스트 모달)주문이 등록되고 감사 페이지가 표시됨

터미널을 통한 테스트:

# 홈페이지가 200 OK를 반환하는지 확인
curl -s -I "https://<your-storefront>.vercel.app" | head -n 5

# 스토어프론트 프록시를 통한 API 연결 확인
curl -s "https://<your-storefront>.vercel.app/api/cart/validate" \
  -H "Content-Type: application/json" \
  -d '{"items":[]}'
# 유효한 JSON 응답 예상

사용자 정의 도메인 설정

Vercel 스토어프론트에 사용자 정의 도메인을 연결하려면:

  1. Vercel Dashboard: 프로젝트 → Settings → Domains
  2. 도메인 입력 (예: store.yourdomain.com 또는 yourdomain.com).
  3. DNS 레코드 구성:
    • 하위 도메인(store.yourdomain.com): cname.vercel-dns.com을 가리키는 CNAME 레코드 추가
    • APEX 도메인(yourdomain.com): 76.76.21.21을 가리키는 A 레코드 추가
  4. SSL 인증서 발급 대기 (Let's Encrypt를 통해 자동).

문제 해결

문제원인해결 방법
빌드 실패: Cannot find module '@astrojs/vercel'cod-astro/theme01에 종속성 누락리포지토리 루트에서 npm install @astrojs/vercel --workspace=cod-astro-theme01 실행
빌드가 Vercel 출력 대신 Cloudflare 출력을 생성함DEPLOY_TARGET이 vercel로 설정되지 않음Vercel 환경 변수에 DEPLOY_TARGET=vercel이 있는지 확인하거나 npm run build:vercel 실행
스토어프론트가 로드되지만 빈 제품 / 오류 배너 표시COD_SERVER_URL이 잘못되었거나 연결할 수 없음COD_SERVER_URL에 https:// 접두사가 있고 라이브 API 작업자와 일치하는지 확인. curl https://<api-url>/api/docs가 200을 반환하는지 확인
주문이 401 Unauthorized로 실패STORE_API_KEY 불일치Vercel의 STORE_API_KEY 값이 codflow-setup 5단계에서 D1 데이터베이스에 시드된 키와 일치해야 함. Vercel에서 비밀을 다시 확인하거나 업데이트
모노레포 빌드가 공유 패키지를 확인하지 못함Vercel 루트 디렉토리 구성Git 통합을 사용하는 경우 Vercel 프로젝트 설정에서 "루트 디렉토리 외부의 소스 파일 포함" 이 활성화되어 있는지 확인하거나, cod-astro/theme01 내에서 npx vercel을 통해 배포
Node.js 버전 경고: Node.js 26은 지원되지 않습니다Vercel 서버리스 함수는 Node 24까지만 지원Node 26 개발 머신에서의 일반적인 경고; Vercel은 클라우드 함수에서 자동으로 Node 24를 실행
R2에서 이미지가 로드되지 않음MEDIA_DOMAIN이 잘못 구성되었거나 CORS 누락MEDIA_DOMAIN이 설정되어 있는지 확인(호스트 이름만, https:// 제외). R2 버킷 CORS 정책이 Vercel 도메인의 요청을 허용하는지 확인

관련 스킬

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community