Índice

• Resumo Estratégico
• 1. Quando usar Pages e quando usar Workers
• 2. Limites importantes do plano gratuito

  • Dica pouco comum
• 3. O problema clássico das SPAs: as rotas profundas

  • Dica pouco comum
• 4. Variáveis de ambiente: públicas não significa secretas

  • Dica pouco comum
• 5. Não coloque toda a API dentro de uma SPA

  • Dica pouco comum: não invoque Functions para tudo
• 6. Use o domínio personalizado no final do deployment
• 7. Proteja a origem e a API
• 8. Aproveite os Preview Deployments

  • Dica pouco comum
• 9. Use R2 para arquivos grandes
• 10. Evite o cache agressivo durante o desenvolvimento
• 11. Métricas que você deve monitorar
• Arquitetura recomendada para começar
• Conclusão

Resumo Estratégico

Necessidade	Ferramenta	Recomendação
Implantar o frontend	Cloudflare Pages	Conectar o repositório Git e implantar automaticamente
Servir arquivos estáticos	Pages CDN	Aproveitar que as solicitações de assets são gratuitas e ilimitadas
Gerenciar domínios	Cloudflare DNS	Usar domínio personalizado e registros proxyados
Proteger a aplicação	WAF Custom Rules	Proteger login, registro e endpoints sensíveis
Criar uma API pequena	Pages Functions ou Workers	Usá-los para lógica leve e endpoints simples
Armazenar arquivos	R2	Separar imagens, PDFs e arquivos grandes do frontend
Guardar dados simples	KV ou D1	Utilizá-los para configuração, sessões ou protótipos
Proteger formulários	Turnstile	Adicioná-lo apenas onde existir abuso
Manipular rotas SPA	_redirects ou _routes.json	Enviar as rotas desconhecidas para index.html
Gerenciar segredos	Variables and Secrets	Nunca incluir chaves privadas no bundle do frontend
Validar mudanças	Preview Deployments	Revisar cada pull request antes da produção
Controlar custos	Limites e análise	Medir Pages Functions e Workers separadamente

1. Quando usar Pages e quando usar Workers

Para uma SPA tradicional, o ponto de partida mais simples é o Cloudflare Pages.

O Pages é adequado quando sua aplicação compila em arquivos estáticos:

npm run build

e gera uma pasta como:

dist/

O fluxo seria:

1. Conectar o repositório Git.
2. Escolher o framework.
3. Definir o comando de build.
4. Indicar a pasta de saída.
5. Implantar automaticamente a cada mudança.

O Cloudflare Pages permite configurar comandos, pastas de saída, variáveis de ambiente e presets para diferentes frameworks. (Build configuration)

Use Workers quando você precisar de:

• Uma API personalizada.
• Middleware avançado.
• Autenticação.
• Transformação de solicitações.
• Lógica executada na edge.
• Um projeto que combine frontend e backend em um mesmo deployment.

A recomendação prática é:

Comece com Pages para o frontend e adicione Workers ou Pages Functions apenas quando tiver uma necessidade concreta de backend.

2. Limites importantes do plano gratuito

O plano gratuito do Pages permite até 500 builds mensais, uma compilação simultânea, 20.000 arquivos por site e um tamanho máximo de 25 MiB por arquivo. Também permite deployments de preview ilimitados. (Pages Limits)

Isso é suficiente para muitas aplicações pessoais, MVPs e projetos pequenos.

No entanto, não é conveniente fazer upload diretamente para o Pages:

• Vídeos grandes.
• Instaladores.
• Backups.
• Arquivos multimídia pesados.
• Coleções grandes de imagens.

Para isso, é melhor usar R2 ou armazenamento especializado e deixar o Pages exclusivamente para a aplicação.

Dica pouco comum

Conte os arquivos gerados pelo seu build:

Get-ChildItem -Recurse dist | Measure-Object

Uma aplicação pode parecer pequena em megabytes, mas exceder o limite de arquivos devido a mapas de origem, traduções, fontes ou assets duplicados.

3. O problema clássico das SPAs: as rotas profundas

Uma SPA pode funcionar perfeitamente ao navegar desde /, mas mostrar um erro 404 se o usuário entrar diretamente em:

/dashboard
/settings/profile
/projects/123

Isso acontece porque o servidor procura um arquivo físico chamado dashboard ou settings/profile, embora essas rotas devessem ser interpretadas pelo roteador do frontend.

A solução é redirecionar as rotas desconhecidas para index.html.

Em muitos projetos do Pages, você pode criar um arquivo _redirects dentro da pasta pública:

/* /index.html 200

O código 200 indica que o navegador deve receber o conteúdo de index.html sem converter a rota em um redirecionamento visível.

Dica pouco comum

Não aplique este fallback indiscriminadamente a arquivos estáticos ou APIs. Uma configuração mal planejada pode converter erros reais como estes:

/api/users
/assets/logo.svg
/favicon.ico

em respostas HTML de index.html.

Teste sempre:

• A rota principal.
• Uma rota interna.
• Uma rota inexistente.
• O recarregamento do navegador.
• Um link compartilhado diretamente.
• O acesso a partir de um dispositivo móvel.

4. Variáveis de ambiente: públicas não significa secretas

Uma SPA é executada no navegador. Portanto, qualquer variável incluída durante o build pode acabar sendo visível para o usuário.

É válido expor:

VITE_API_URL
NEXT_PUBLIC_API_URL
PUBLIC_SUPABASE_URL

Mas você nunca deve expor:

DATABASE_PASSWORD
STRIPE_SECRET_KEY
JWT_PRIVATE_KEY
CLOUDFLARE_API_TOKEN

As variáveis públicas podem ser usadas para configurar o frontend. Os segredos devem permanecer em Pages Functions, Workers ou seu backend.

O Cloudflare permite configurar variáveis diferentes para produção e preview a partir do painel do projeto. (Pages Bindings)

Dica pouco comum

Crie dois ambientes separados:

Preview → API de testes
Production → API real

Assim, você pode revisar um pull request sem que o frontend de teste modifique dados reais.

Além disso, defina explicitamente a versão do Node.js através de .nvmrc, .node-version ou NODE_VERSION. Isso evita que uma mudança no ambiente de build quebre o deployment inesperadamente. (Pages Build Image)

5. Não coloque toda a API dentro de uma SPA

Uma SPA não deve se comunicar diretamente com serviços que exigem chaves privadas.

Arquitetura insegura:

SPA → Serviço externo usando chave secreta

Arquitetura recomendada:

SPA → Worker ou Pages Function → Serviço externo

O Worker pode:

• Validar os dados recebidos.
• Verificar autenticação.
• Aplicar rate limiting.
• Ocultar as credenciais.
• Normalizar respostas.
• Registrar erros.

As Pages Functions são executadas como Workers e suas solicitações contam dentro da cota de Workers. No plano gratuito, a cota combinada é de 100.000 solicitações diárias. (Pages Functions Pricing)

Dica pouco comum: não invoque Functions para tudo

Se você adicionar uma Function a um projeto Pages sem configurar rotas, pode acabar executando lógica dinâmica para solicitações que deveriam apenas servir arquivos estáticos.

Configure as rotas para que a Function responda apenas a:

/api/*

e deixe os assets como conteúdo estático. O Cloudflare permite definir rotas de inclusão e exclusão para controlar quais solicitações invocam Functions. (Pages Functions Routing)

6. Use o domínio personalizado no final do deployment

Primeiro teste a aplicação em:

my-app.pages.dev

Depois conecte:

app.example.com

Isso facilita separar:

app.example.com       → produção
staging.example.com   → testes
api.example.com       → API
assets.example.com    → arquivos grandes

Ative o proxy do Cloudflare para o tráfego HTTP e HTTPS, mas deixe como DNS-only os serviços que não são compatíveis com o proxy web, como alguns registros de correio.

7. Proteja a origem e a API

Se o frontend está no Pages mas a API vive em outro servidor, proteja também essa origem.

Medidas recomendadas:

• Não revelar desnecessariamente o IP do backend.
• Aplicar autenticação na API, não apenas no frontend.
• Validar CORS.
• Limitar solicitações a /api/login, /api/register e /api/reset-password.
• Usar Turnstile em formulários atacados.
• Aplicar Managed Challenge antes de bloquear usuários.

As regras personalizadas do Cloudflare permitem realizar ações como bloquear ou desafiar solicitações. No plano gratuito existem limites de quantidade e funcionalidade, por isso convém reservá-las para rotas críticas. (Custom Rules)

8. Aproveite os Preview Deployments

Uma das funções mais úteis para equipes pequenas é ter uma URL de preview por pull request.

O fluxo recomendado:

Pull request
   ↓
Preview deployment
   ↓
Testes visuais e funcionais
   ↓
Merge para produção

Isso é especialmente importante para SPAs porque permite detectar:

• Rotas que retornam 404.
• Variáveis de ambiente ausentes.
• Erros de CORS.
• Mudanças quebradas em dispositivos móveis.
• Problemas de cache.
• Falhas de autenticação.

Dica pouco comum

Inclua em sua aplicação uma pequena etiqueta visual que indique o ambiente:

Preview · commit a81f2c

Assim, ninguém confunde uma URL de teste com produção durante uma revisão.

9. Use R2 para arquivos grandes

O bundle de uma SPA deve conter apenas o necessário para executar a aplicação.

Guarde fora do Pages:

• Imagens enviadas por usuários.
• Vídeos.
• PDFs.
• Arquivos de projetos.
• Backups.
• Exportações geradas.

O R2 é projetado para armazenamento de objetos e pode ser usado com Workers ou sua própria API. Na oferta atual do Cloudflare, o plano gratuito inclui uma cota de armazenamento e operações para R2. (Cloudflare Plans)

Uma arquitetura simples seria:

SPA → Worker → R2

O Worker gera URLs controladas e evita que o bucket seja um ponto de acesso completamente aberto.

10. Evite o cache agressivo durante o desenvolvimento

O Cloudflare pode fazer cache de arquivos de frontend por muito tempo. Isso é positivo na produção, mas pode ser frustrante quando você está desenvolvendo.

Para evitar problemas:

• Use nomes com versão para CSS e JavaScript.
• Não faça cache de respostas privadas.
• Purge URLs específicas em vez de purgar tudo.
• Use o modo Development Mode durante mudanças rápidas.
• Verifique CF-Cache-Status.
• Lembre-se que o cache do navegador pode sobreviver a um purge do Cloudflare.

O plano gratuito permite Cache Rules, purge de cache e análise de cache, embora com limites inferiores aos planos superiores. (Cache Features by Plan)

11. Métricas que você deve monitorar

Para uma SPA, não basta medir visitas.

Observe:

• Tempo de carregamento do JavaScript principal.
• Porcentagem de respostas em cache.
• Erros 404 em rotas internas.
• Erros 4xx e 5xx da API.
• Solicitações a Functions.
• Uso diário de Workers.
• Tempo de CPU por solicitação.
• Taxa de erros de autenticação.
• Tamanho do bundle.
• Taxa de abandono em formulários.

O plano gratuito dos Workers tem um limite de 100.000 solicitações diárias e 10 ms de CPU por solicitação. Uma função pequena pode funcionar bem, mas uma função que processa imagens, autentica usuários complexos ou realiza cálculos pesados pode exceder esse limite. (Workers Limits)

Arquitetura recomendada para começar

Cloudflare DNS
      ↓
Cloudflare Pages
      ↓
SPA estática
      ↓
Pages Functions / Workers
      ↓
Banco de dados externo ou D1
      ↓
R2 para arquivos

Para um MVP, você pode começar com:

• Pages para o frontend.
• Um Worker ou Pages Function para a API.
• Supabase, Neon ou D1 para o banco de dados.
• R2 para arquivos.
• Turnstile para formulários sensíveis.
• Preview Deployments para revisar mudanças.

Conclusão

A camada gratuita do Cloudflare é especialmente interessante para implantar SPAs porque combina hosting estático, CDN, HTTPS, domínios personalizados, previews e funções serverless.

A estratégia mais eficiente é:

1. Implantar primeiro o frontend no Pages.
2. Resolver corretamente as rotas da SPA.
3. Separar variáveis públicas de segredos.
4. Usar Functions ou Workers apenas para lógica dinâmica.
5. Guardar arquivos grandes no R2.
6. Proteger login, registro e API.
7. Medir consumo, erros e desempenho.
8. Escalar apenas quando existir um limite real.

O Cloudflare não substitui automaticamente todo o backend, mas permite construir uma aplicação web funcional, segura e bastante econômica com uma arquitetura modular.