Cloudflare Pages의 바닐라 정적 사이트
빌드 단계 없음. 파일 편집 → main에 푸시 → Cloudflare Pages가 자동 배포합니다.
빠르고, 저렴하며, 도구 체인과 싸울 일이 없습니다.
바닐라를 선택한 이유 (결정 근거)
- 빌드/CI 변경 사항이 전혀 없음. 두 줄 복사 수정은 30초 배포.
- 프레임워크 종속이나 재작성 비용 없음. "추가하되, 재작성하지 마라"가 원칙.
- 전체 사이트를 grep 가능하고, 디버깅 가능하며, 명확함.
- 수용한 트레이드오프: 더 많은 수동 DOM 코드. 소규모/중간 규모에서 충분히 가치 있음.
저장소 + 배포
- 하나의 GitHub 저장소 → Cloudflare Pages 프로젝트,
main브랜치 푸시 시 자동 배포. - Pages는 저장소 루트를 제공합니다. 예쁜 URL:
/mi-cuenta.html은/mi-cuenta로 제공. - 함수(서버리스)는
/functions디렉토리에 위치합니다 (supabase-backend참조).
배포 의례 (모든 배포 시 수행)
- 파일 편집.
- JS 컴파일 확인 — 깨진 인라인 JS를 푸시하지 마세요. 인라인
<script>블록을 추출하여 각각vm.compileFunction실행;.js/.cjs파일은node --check사용.reference/verify-inline.cjs참조. - 애셋 캐시 무효화:
node .claude/cache-bust.cjs실행 — HTML 내 모든assets/**/*.css|js참조에?v=<git-short-hash>스탬프를 찍고version.json을 작성합니다.reference/cache-bust.cjs참조. - 버전 스탬프 업데이트 (하나의 JS 파일에 단일 진실 공급원, 푸터에 미묘하게 표시)
및 기록. 버전 관리 체계는
project-continuity참조. - 커밋 (설명적이며, 프로젝트 언어로) 공동 작성자 트레일러 포함,
main브랜치로 푸시. - 라이브 확인:
curl로 배포된 애셋을 가져와 새 버전 스탬프 확인 +version.json이 애셋?v=와 일치하는지 확인 (일치하지 않으면 자동 리로더가 루프에 빠짐). Cloudflare 봇 보호가 일반 크롤러를 차단하므로 브라우저 User-Agent 사용.
.claude/는 일반적으로 gitignore 처리되므로 캐시 무효화/확인 스크립트는 로컬에 남습니다. (저장소가 아닌 로컬 머신의 빌드 시점에 실행됩니다.)
캐시 무효화 + 자동 새로고침 ("안 보임" 전화 게임 제거)
reference/에 두 가지 레이어:
cache-bust.cjs— 배포 시 모든 애셋 참조에?v=<git hash>를 다시 스탬프하여 브라우저가 변경된 CSS/JS를 다시 가져오도록 하고,version.json = {"v":"<hash>"}를 작성합니다.- 자동 리로더 (
reference/auto-reload.js) — 모든 페이지에 포함된 작은 스크립트로, 자신이 로드된?v=를 읽고/version.json을 폴링하며(no-store로 제공), 새 배포가 감지되면: 탭 복귀 시 (안전한 순간) 리로드하고, 사용자가 보고 있을 때 한 번 탭으로 "업데이트" 배너를 표시하며, 입력 중에는 절대 중단하지 않습니다 (window.__noAutoReload로 시험/결제 흐름에서 옵트아웃 가능). 부트스트랩 주의사항: 처음에는 사용자가 하드 새로고침을 한 번 해서 리로더를 로드해야 하며, 그 이후부터는 자동으로 작동합니다.
_headers를 통해 마커를 신선하게 제공:
/version.json
Cache-Control: no-store, max-age=0
보안 헤더 (저장소 루트의 _headers)
항상 설정: Content-Security-Policy (script-src/frame-src/connect-src를
정확한 CDN + Supabase URL + 실시간용 wss로 고정), X-Frame-Options: DENY,
X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin,
Permissions-Policy, Strict-Transport-Security. 경험상 함정: 비디오 iframe을 포함하려면
플레이어 도메인이 frame-src에 있어야 하며, 그렇지 않으면 브라우저가 조용히 차단합니다.
재사용 가능한 CSS 규칙
- CSS 변수를 사용한 토큰 기반 테마;
data-theme="dark"재매핑 + 공유localStorage키로 페이지/탭 간 테마 동기화. - 다크 모드: 대비 통과만으로 충분하지 않음 — 가시적인 계층 구조 (bg < surface < card)를 밝기 단계 + 그림자로 제공해야 하며, 그렇지 않으면 평면적으로 읽힘.
white/색상을 하드코딩하지 말고 토큰을 사용하여 테마가 반응하도록 함.- 전역
.btn/.btn-primary를 깨지 말고, 범위 내에서 재정의.
이 스킬의 파일
reference/cache-bust.cjs— 애셋 스탬퍼 + version.json 작성기.reference/auto-reload.js— 배포 자동 리로더 (전역 로드 JS 파일에 포함).reference/verify-inline.cjs— 배포 전 인라인<script>블록 컴파일 확인.reference/headers-example— 시작용_headers.