vanilla-site-cloudflare

Site estático vanilla no Cloudflare Pages

Sem etapa de build. Edite os arquivos → faça push para main → Cloudflare Pages faz deploy automático. Rápido, barato e você nunca briga com uma toolchain.

Por que vanilla (justificativa da decisão)

• Zero churn de build/CI; uma correção de 2 linhas é um deploy de 30 segundos.
• Sem lock-in de framework ou taxa de reescrita. "Adicione, não reescreva" é a regra.
• O site inteiro é pesquisável, depurável e óbvio.
• Trade-off aceito: mais código DOM manual. Vale a pena em escala pequena/média.

Repositório + Deploy

• Um repositório GitHub → projeto Cloudflare Pages, deploy automático ao fazer push para main.
• Pages serve a raiz do repositório. URLs bonitas: /mi-cuenta.html é servido em /mi-cuenta.
• Functions (serverless) ficam em /functions (veja supabase-backend).

O ritual de deploy (faça isso em CADA deploy)

1. Edite os arquivos.
2. Verifique se o JS compila — nunca envie JS inline quebrado. Extraia blocos <script> inline e execute vm.compileFunction em cada um; node --check para arquivos .js/.cjs. Veja reference/verify-inline.cjs.
3. Quebre o cache dos assets: node .claude/cache-bust.cjs — carimba cada referência a assets/**/*.css|js no HTML com ?v=<git-short-hash> e escreve version.json. Veja reference/cache-bust.cjs.
4. Atualize o carimbo de versão (fonte única de verdade em um arquivo JS, mostrado sutilmente no rodapé) e registre-o. Veja project-continuity para o esquema de versionamento.
5. Faça commit (descritivo, no idioma do projeto) com o trailer de coautor, faça push para main.
6. Verifique ao vivo: faça curl no asset implantado e confirme o novo carimbo de versão + que version.json é igual ao ?v= do asset (eles devem coincidir ou o recarregador automático entra em loop). A proteção contra bots do Cloudflare bloqueia crawlers comuns → use um User-Agent de navegador.

.claude/ normalmente está no .gitignore, então os scripts de quebra de cache/verificação ficam locais (eles são executados em tempo de build na sua máquina, não no repositório).

Quebra de cache + Recarga automática (mata o jogo de telefone "não aparece")

Duas camadas, ambas em reference/:

1. cache-bust.cjs — recarimba ?v=<hash git> em todas as referências de asset a cada deploy para que os navegadores baixem novamente CSS/JS alterados, E escreve version.json = {"v":"<hash>"}.
2. Recarregador automático (reference/auto-reload.js) — um script minúsculo incluído em cada página que lê seu próprio ?v= carregado, consulta /version.json (servido com no-store), e quando um novo deploy é detectado: recarrega ao retornar à aba (momento seguro), mostra um banner "Actualizar" de um toque enquanto você está olhando, e nunca interrompe durante a digitação (opt-out window.__noAutoReload para fluxos de prova/checkout). Ressalva de inicialização: na primeira vez, os usuários dão um hard refresh uma vez para carregar o recarregador; a partir daí é automático.

Sirva o marcador sempre fresco via _headers:

/version.json
  Cache-Control: no-store, max-age=0

Cabeçalhos de segurança (_headers na raiz do repositório)

Sempre defina: Content-Security-Policy (trave script-src/frame-src/connect-src para os CDNs exatos + sua URL do Supabase + wss para tempo real), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy, Strict-Transport-Security. Pegadinha vivida: incorporar um iframe de vídeo precisa do domínio do player em frame-src ou o navegador o bloqueia silenciosamente.

Convenções CSS reutilizáveis

• Tematização baseada em tokens com variáveis CSS; um remapeamento data-theme="dark" + uma chave compartilhada de localStorage para que o tema sincronize entre páginas/abas.
• Modo escuro: passar no contraste não é suficiente — você também precisa de uma hierarquia de camadas visível (bg < surface < card) com passos claros + sombra, ou fica plano.
• Nunca codifique white/cores diretamente; use tokens para que o tema responda.
• Não quebre .btn/.btn-primary globais; sobrescreva no escopo.

Arquivos neste skill

• reference/cache-bust.cjs — o carimbador de assets + escritor de version.json.
• reference/auto-reload.js — o recarregador automático de deploy (insira em um arquivo JS carregado globalmente).
• reference/verify-inline.cjs — verificação de compilação de blocos <script> inline antes do deploy.
• reference/headers-example — um _headers inicial.