Cloudflare 배포
이 문서 사이트와 shadcn registry 를 정적 사이트로 빌드해서 Cloudflare 에 배포하는 방법이에요.
문서 사이트(apps/docs)는 React Router v7 + Vite 로 만들고, ssr: false 로 모든 페이지를 빌드 시점에 HTML 로 프리렌더해요. 서버가 필요 없어서 Cloudflare Workers 의 정적 자산(Static Assets)으로 그대로 올릴 수 있어요.
빌드 결과물
pnpm build 는 아래 순서로 실행돼요.
pnpm tokens:build—brands/*YAML 검증 + 토큰 빌드scripts/build-registry.ts—public/r/*.json(컴포넌트,<brand>-theme,registry.json)react-router build— 모든 문서 페이지,llms.txt,llms-full.txt, 페이지별 Markdown 프리렌더scripts/postbuild.ts—404.html생성
결과물은 apps/docs/build/client 에 모여요.
VITE_SITE_URL 설정
registry 아이템의 의존성 URL(registryDependencies)과 문서의 설치 명령은 빌드할 때 사이트 주소를 넣어 만들어요. 배포할 도메인을 VITE_SITE_URL 로 꼭 지정해요. 지정하지 않으면 http://localhost:5173 이 들어가요.
VITE_SITE_URL=https://design.example.com pnpm build끝에 / 를 붙이지 않아요. 도메인을 바꿨다면 다시 빌드해야 registry JSON 안의 URL 이 바뀌어요.
직접 배포하기
Wrangler 로그인
pnpm --filter docs exec wrangler login빌드 + 배포
저장소 루트에서 실행해요. pnpm cf:deploy 는 빌드 후 wrangler deploy 를 실행해요.
스크립트 이름이 deploy 가 아닌 이유: pnpm deploy 는 pnpm 내장 명령(워크스페이스 패키지 배포)과 겹치기 때문이에요.
VITE_SITE_URL=https://design.example.com pnpm cf:deploy로컬에서 미리 보기 (선택)
배포 전에 Cloudflare 런타임과 같은 환경에서 결과물을 확인할 수 있어요.
pnpm build
pnpm --filter docs preview # wrangler devwrangler 설정
apps/docs/wrangler.jsonc 는 정적 자산만 배포하도록 설정돼 있어요.
{
"name": "rebar",
"compatibility_date": "2026-10-01",
"assets": {
"directory": "./build/client",
"not_found_handling": "404-page",
"html_handling": "auto-trailing-slash"
}
}| 항목 | 의미 |
|---|---|
name | Worker 이름. <name>.<계정>.workers.dev 주소가 돼요. |
assets.directory | 업로드할 정적 파일 폴더 |
not_found_handling | 없는 경로는 404.html 을 보여줘요 |
html_handling | /components/action-button 같은 경로를 index.html 로 연결해요 |
커스텀 도메인은 Cloudflare 대시보드의 Workers & Pages → 해당 Worker → Settings → Domains & Routes 에서 연결해요.
Git 연동 자동 배포
Cloudflare 대시보드에서 저장소를 연결하면 푸시할 때마다 자동으로 배포돼요.
| 설정 | 값 |
|---|---|
| Root directory | / (저장소 루트) |
| Build command | pnpm build |
| Deploy command | pnpm --filter docs run cf:deploy |
| 환경 변수 (빌드) | VITE_SITE_URL=https://design.example.com |
Node.js 는 22.18 이상이 필요해요. 빌드 환경 변수에 NODE_VERSION=22.18.0 이상을 지정해요.
배포 후 확인
https://<도메인>/r/registry.json이 열리고homepage가 배포 도메인인지 확인해요.https://<도메인>/r/clay-theme.json을 다른 프로젝트에서shadcn add로 설치해 봐요.https://<도메인>/llms.txt가 열리는지 확인해요.