Quando publiquei a primeira versão deste conteúdo, o Cloudflare Pages era apresentado principalmente como uma plataforma JAMstack. Desde então, o produto ganhou Pages Functions, deploy pela linha de comando e integração mais profunda com Workers.

O Cloudflare Pages continua sendo uma opção para publicar sites estáticos e manter projetos existentes. No entanto, existe uma mudança importante: a Cloudflare agora recomenda Workers Static Assets para projetos novos.

Neste guia, você vai entender como o Cloudflare Pages funciona, como configurar um deploy e quando escolher Workers.

O que é Cloudflare Pages?

Cloudflare Pages é uma plataforma para publicar sites e aplicações na rede global da Cloudflare. Você pode conectar um repositório Git, enviar arquivos prontos ou fazer o deploy com Wrangler.

A plataforma atende projetos como:

• sites estáticos em HTML, CSS e JavaScript;
• documentações e blogs gerados com Hugo, Astro ou Eleventy;
• single-page applications criadas com React, Vue ou outros frameworks;
• aplicações com pequenas funções de back-end usando Pages Functions;
• projetos que precisam de ambientes automáticos de preview.

Além disso, o Pages configura HTTPS e distribui os arquivos pela infraestrutura da Cloudflare. Isso reduz a necessidade de configurar servidores, certificados e uma CDN separadamente.

Se o conceito de execução sem servidor ainda for novo para você, leia também o conteúdo sobre o que é serverless.

Como o Cloudflare Pages funciona?

O fluxo mais comum começa com um repositório no GitHub ou GitLab. Depois de conectar o repositório, você informa a branch de produção, o comando de build e a pasta de saída.

Por exemplo, um projeto criado com Vite normalmente usa:

Build command: npm run build
Build output directory: dist

Quando você envia um commit para a branch de produção, o Pages executa o build e publica o resultado. Por outro lado, commits em outras branches podem gerar deployments de preview.

A pasta de saída é importante porque ela contém os arquivos que a plataforma enviará para a rede global. Portanto, confira a documentação do framework antes de configurar esse campo.

Como fazer deploy no Cloudflare Pages com Git

Antes de começar, envie o seu projeto para um repositório no GitHub ou GitLab. Em seguida, abra a área Workers & Pages no painel da Cloudflare.

O fluxo de configuração segue estes passos:

1. Crie uma aplicação Pages e escolha a integração com Git.
2. Autorize o acesso ao GitHub ou GitLab.
3. Selecione o repositório que contém o projeto.
4. Defina a production branch, geralmente main.
5. Informe o build command, como npm run build.
6. Informe o build output directory, como dist.
7. Revise as variáveis de ambiente necessárias.
8. Inicie o primeiro deploy.

Depois disso, novos commits na production branch iniciam builds automáticos.

git add .
git commit -m "Atualiza a página inicial"
git push origin mainCode language: JavaScript (javascript)

O git push continua sendo suficiente para disparar o processo. Além disso, o painel mantém os logs de build, o histórico de deployments e a opção de rollback.

A documentação de Git integration contém detalhes sobre permissões, branches e variáveis de ambiente.

Como funcionam os deployments de preview?

Os previews permitem testar alterações antes de publicar em produção. Em um projeto conectado ao GitHub, uma pull request criada dentro do próprio repositório recebe uma URL exclusiva.

Essa URL continua atualizada quando novos commits chegam à branch. Assim, o time pode revisar design, conteúdo e comportamento sem alterar o domínio principal.

Por padrão, o Cloudflare Pages envia o header abaixo nos deployments de preview:

X-Robots-Tag: noindexCode language: HTTP (http)

Esse header reduz o risco de mecanismos de busca indexarem uma cópia temporária do site. Você pode conferir o comportamento com:

curl -I https://sua-preview.pages.devCode language: JavaScript (javascript)

Vale notar que pull requests originadas em forks externos não recebem o mesmo comportamento automático. Portanto, valide o fluxo de preview quando o projeto aceita contribuições externas.

Como fazer deploy com Wrangler

A integração com Git não é a única opção. O Direct Upload permite publicar arquivos gerados localmente ou por outra ferramenta de CI.

Primeiro, autentique o Wrangler:

npx wrangler login

Depois, crie um projeto Pages:

npx wrangler pages project create

Gere os arquivos do projeto e envie a pasta de saída:

npm run build
npx wrangler pages deploy dist

Para criar um preview associado a uma branch, use:

npx wrangler pages deploy dist --branch=feature-nova-home

O Pages disponibilizará a produção em um domínio semelhante a projeto.pages.dev. A branch também receberá um alias próprio.

Existe uma limitação importante nessa escolha. Um projeto criado como Direct Upload não pode migrar para Git integration. Da mesma forma, um projeto criado com Git integration não se transforma em Direct Upload. Nesse caso, você precisa criar outro projeto.

Consulte o guia de Direct Upload antes de decidir o fluxo.

Como adicionar uma API com Pages Functions

O Cloudflare Pages também pode executar código no servidor por meio de Pages Functions. Essa funcionalidade utiliza o runtime de Cloudflare Workers.

Por exemplo, crie o arquivo functions/api/status.js:

export async function onRequestGet() {
  return Response.json({
    status: "online",
    timestamp: new Date().toISOString(),
  });
}Code language: JavaScript (javascript)

Depois do deploy, a função ficará disponível em:

https://seu-projeto.pages.dev/api/statusCode language: JavaScript (javascript)

Esse modelo atende endpoints simples, formulários, autenticação e middleware. Além disso, uma Function pode acessar recursos como KV, D1 e R2 por meio de bindings.

Entretanto, requisições que executam Pages Functions entram na cota do plano Workers. Requisições apenas para arquivos estáticos continuam gratuitas e ilimitadas.

Para controlar quais rotas invocam Functions, revise o arquivo _routes.json. Isso evita executar código dinâmico para imagens, folhas de estilo e outros assets estáticos.

Leia também a introdução a Cloudflare Workers para entender melhor o runtime.

Como configurar um domínio personalizado

Todo projeto recebe um subdomínio pages.dev. Contudo, você também pode associar um domínio próprio pelo painel.

Para isso:

1. Abra Workers & Pages.
2. Selecione o projeto.
3. Entre em Custom domains.
4. Escolha Set up a domain.
5. Informe o domínio ou subdomínio desejado.

Para usar um domínio apex, como exemplo.com, a zona precisa estar na mesma conta da Cloudflare. Além disso, os nameservers devem apontar para a Cloudflare.

No caso de um subdomínio, como app.exemplo.com, você pode usar um CNAME apontando para projeto.pages.dev. Mesmo assim, associe primeiro o domínio no painel do Pages. Criar apenas o registro DNS pode resultar em erro 522.

Quais são os limites do plano gratuito?

Os limites podem mudar. Portanto, confira sempre a página oficial de limites.

Em julho de 2026, os principais limites do plano Free são:

Recurso	Limite
Builds simultâneos	1
Builds por mês	500
Tempo máximo de build	20 minutos
Domínios personalizados	100 por projeto
Arquivos por site	20.000
Tamanho máximo por arquivo	25 MiB
Projetos por conta	100
Previews ativos	Ilimitados
Requisições para assets estáticos	Gratuitas e ilimitadas

Pages Functions seguem os limites e a cobrança do plano Workers. Por isso, um site estático e uma aplicação full-stack podem ter custos diferentes.

Arquivos maiores que 25 MiB devem ir para um serviço apropriado, como o Cloudflare R2.

Cloudflare Pages ou Workers Static Assets?

Esta é a principal mudança desde a primeira versão do post.

A Cloudflare recomenda Workers Static Assets para novos sites, SPAs e aplicações full-stack. O Pages continua operacional, mas os novos recursos e otimizações estão concentrados em Workers.

Um site estático em Workers precisa apenas de um arquivo wrangler.jsonc:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "meu-site",
  "compatibility_date": "2026-07-21",
  "assets": {
    "directory": "./dist"
  }
}Code language: JSON / JSON with Comments (json)

Depois do build, publique com:

npx wrangler deploy

Nesse exemplo, o projeto nem precisa de um Worker script. O próprio Workers Static Assets publica e distribui os arquivos.

Use esta orientação prática:

• mantenha projetos Pages existentes quando o fluxo atual atende às necessidades;
• use Workers Static Assets ao iniciar um projeto novo;
• considere a migração quando precisar de Durable Objects, Cron Triggers ou observabilidade mais completa;
• para Next.js com SSR, siga o guia de Next.js para Workers;
• use Pages apenas para uma exportação estática de Next.js.

A Cloudflare oferece um guia de migração do Pages para Workers. Entretanto, não existe necessidade de migrar apenas porque o produto recebeu uma nova recomendação.

O Cloudflare Pages ainda vale a pena?

O Cloudflare Pages ainda entrega um fluxo simples para sites existentes conectados ao GitHub ou GitLab. Os deployments automáticos, previews e rollbacks continuam úteis.

Por outro lado, Workers Static Assets se tornou o caminho recomendado para projetos novos. Ele combina assets estáticos, APIs e recursos da plataforma em uma única configuração.

Em resumo, o Pages permanece válido. Porém, entender a direção atual da plataforma evita começar um projeto novo sobre um fluxo que receberá menos recursos no futuro.

Para continuar estudando a infraestrutura, confira também como funciona a CDN da Cloudflare.

Referências

• Cloudflare Pages
• Git integration
• Direct Upload e Wrangler
• Pages Functions
• Workers Static Assets para projetos novos
• Migração de Pages para Workers