Cloudflare Pages

Implante projetos frontend com builds de pré-visualização, funções de edge e entrega de CDN global na rede da Cloudflare.

Quando Usar

• Implantação de sites estáticos (React, Vue, Astro, Hugo, exportação estática do Next.js).
• Aplicações full-stack usando Pages Functions para lógica do lado do servidor.
• Projetos que precisam de implantações automáticas de pré-visualização por pull request.
• Equipes que desejam CDN sem configuração com domínio personalizado e TLS.
• Migração de Vercel, Netlify ou GitHub Pages para o ecossistema da Cloudflare.

Pré-requisitos

• Node.js 18+ e npm instalados localmente.
• Uma conta Cloudflare (o plano gratuito funciona para a maioria dos projetos).
• Wrangler CLI instalado: npm install -g wrangler.
• Autenticado via variável de ambiente wrangler login ou CLOUDFLARE_API_TOKEN.
• Código-fonte em um repositório Git (GitHub ou GitLab para integração com o painel).

Configuração de Projeto via Wrangler

Criar um Novo Projeto

# Create a new Pages project
npx wrangler pages project create my-site

# List existing projects
npx wrangler pages project list

# Delete a project (removes all deployments)
npx wrangler pages project delete my-site

Implantar a Partir da Saída de Build Local

# Build your framework first
npm run build

# Deploy the output directory
npx wrangler pages deploy dist --project-name=my-site

# Deploy with a custom branch name (triggers preview URL)
npx wrangler pages deploy dist --project-name=my-site --branch=feature-auth

# Deploy and get the deployment URL in JSON
npx wrangler pages deploy dist --project-name=my-site --branch=main 2>&1 | tail -1

Listar e Gerenciar Implantações

# List recent deployments
npx wrangler pages deployment list --project-name=my-site

# Tail live logs from a deployment
npx wrangler pages deployment tail --project-name=my-site --environment=production

Integração Git do Painel

1. Navegue até Workers & Pages > Criar aplicação > Pages.
2. Conecte sua conta GitHub ou GitLab.
3. Selecione o repositório e configure:
   • Branch de produção: main
   • Comando de build: npm run build
   • Diretório de saída do build: dist (ou build, .next, public dependendo do framework)
4. Defina variáveis de ambiente por ambiente (Produção vs. Pré-visualização).

Presets de Framework

A Cloudflare detecta frameworks automaticamente. Substitua se necessário:

Implantações de Pré-visualização

Cada branch não-produção recebe automaticamente uma URL de pré-visualização exclusiva.

# URL format for preview deployments
https://<commit-hash>.<project-name>.pages.dev
https://<branch-name>.<project-name>.pages.dev

Controle de Acesso Baseado em Branch

# Set preview branch patterns in wrangler.toml (Pages-specific)
# Or configure via dashboard: Settings > Builds & deployments
# Include branches: feature/*, staging
# Exclude branches: dependabot/*

Comentário de Pré-visualização em Pull Requests

Ative o App GitHub Cloudflare Pages para postar URLs de implantação como comentários de PR. Configure em Configurações > Builds e implantações > Comentário de pré-visualização.

Pages Functions

Pages Functions fornecem lógica do lado do servidor implantada junto com seu site estático. Coloque arquivos em um diretório functions/ na raiz do projeto.

Rota de API Básica

// functions/api/hello.ts
export const onRequestGet: PagesFunction = async (context) => {
  return new Response(JSON.stringify({ message: "Hello from the edge" }), {
    headers: { "Content-Type": "application/json" },
  });
};

// functions/api/users/[id].ts — dynamic route parameter
export const onRequestGet: PagesFunction = async (context) => {
  const userId = context.params.id;
  return new Response(JSON.stringify({ userId }), {
    headers: { "Content-Type": "application/json" },
  });
};

Middleware

// functions/_middleware.ts — executa antes de todas as rotas
export const onRequest: PagesFunction = async (context) => {
  const authHeader = context.request.headers.get("Authorization");
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return new Response("Unauthorized", { status: 401 });
  }

…