GitHub

Times adotam Pages porque o fluxo de git push com build automático e deploy instantâneo é genuinamente mais simples do que montar um pipeline de CI do zero. Isso é uma vantagem real, não marketing. O problema aparece quando o projeto cresce e você começa a bater nos limites que Pages não resolve: cron triggers, múltiplos Workers com responsabilidades separadas, staging com bindings distintos. Nesse ponto a migração para Workers parece óbvia — mas o custo real dela raramente é calculado antes de começar.

Os gatilhos reais de migração

O gatilho mais comum é cron triggers. Pages não suporta cron nativamente. Se você precisa de um job que roda periodicamente — processamento de pagamentos, sincronização de dados externos, geração de relatórios agendados — você já tem um Worker separado rodando ao lado do seu projeto Pages. Quando o número de Workers satélite cresce, o time começa a se perguntar se faria mais sentido consolidar tudo em Workers.

O segundo gatilho é a fragmentação de deploy. Um projeto Pages é uma unidade monolítica de deploy — frontend, Functions, tudo junto. Quando você quer dividir responsabilidades entre Workers especializados (um para a API pública, um para processamento interno, um para webhooks), Pages não oferece essa granularidade. O deploy de uma mudança no handler de webhooks dispara um rebuild do frontend inteiro.

O terceiro é staging com paridade de produção. Pages tem environments de produção e preview, mas não tem environments nomeados com bindings completamente distintos. Se você quer um banco D1 de staging completamente separado do de produção, com variáveis de ambiente diferentes e talvez até um modelo de KV diferente, a solução em Pages é criar um projeto Pages separado e gerenciar a sincronização manualmente. Em Workers, isso fica no wrangler.toml com blocos [env.staging] e [env.production].

O que você perde ao sair do Pages

Antes de migrar, o cálculo correto é listar o que Pages oferece que você vai precisar substituir.

O pipeline de build é o item mais subestimado. Pages conecta ao repositório, detecta o framework, roda o build, e faz upload dos assets. No Workers, você assume essa responsabilidade: CI/CD próprio (GitHub Actions, GitLab CI, o que for), script de build, e upload dos assets para R2 se você ainda precisar servir arquivos estáticos.

Preview deployments por branch são o segundo item. Pages gera automaticamente uma URL de preview para cada branch — push, URL disponível, comentário no PR. Replicar isso em Workers requer trabalho: um script de CI que detecta o nome da branch, faz deploy com um nome de Worker derivado da branch (minha-api-pr-247), e comenta a URL no PR via API do GitHub. Funciona, mas é código de infra que você escreve e mantém.

O terceiro item é o CDN para assets estáticos. Esse é o mais caro de ignorar.

A conta dos assets estáticos

No Pages, assets estáticos (HTML, CSS, JS, imagens) são servidos diretamente do CDN da Cloudflare sem acionar o runtime de Workers. Cada requisição para um asset estático custa $0 por requisição, independente do volume.

No Workers, você não tem essa primitiva nativamente. Para servir assets, você precisa de R2 (armazenamento de objetos) e uma lógica no Worker que busca o asset correto, aplica cache headers e retorna o conteúdo. Cada requisição que passa pelo runtime conta como uma invocação de Worker.

O plano pago de Workers inclui 10 milhões de requisições por mês e cobra $0,30 por milhão acima disso. Um site com 100 milhões de requisições mensais, sendo 90 milhões para assets estáticos: no Pages, o custo de requisição é $0. No Workers, são 90 milhões de invocações acima do pacote incluído — $27/mês só por esse delta, crescendo linearmente com o tráfego.

Para um site de 500 milhões de requisições mensais com 85% de assets estáticos: a diferença chega a mais de $120/mês. O custo do plano pro de Pages é $20/mês. A migração para Workers, nesse cenário, é uma decisão que aumenta custo operacional em troca de flexibilidade.

O wrangler.toml para servir assets de R2

Se a migração faz sentido apesar do custo, o padrão correto para servir assets estáticos em Workers usa R2 com Cache API:

# wrangler.toml
name = "meu-site"
main = "src/index.ts"
compatibility_date = "2024-09-24"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "meu-site-assets"

[[routes]]
pattern = "meusite.com/*"
zone_name = "meusite.com"

// src/index.ts
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const cache = caches.default;
    const cached = await cache.match(request);
    if (cached) return cached;

    const url = new URL(request.url);
    const key = url.pathname.slice(1) || "index.html";
    const object = await env.ASSETS.get(key);

    if (!object) {
      return new Response("Not Found", { status: 404 });
    }

    const response = new Response(object.body, {
      headers: {
        "Content-Type": object.httpMetadata?.contentType ?? "application/octet-stream",
        "Cache-Control": "public, max-age=31536000, immutable",
      },
    });

    await cache.put(request, response.clone());
    return response;
  },
};

Isso replica o comportamento de CDN do Pages, mas você está pagando por cada miss de cache (primeira requisição por arquivo por PoP da Cloudflare). O CDN do Pages tem essa camada de cache sem custo adicional por requisição.

Como fazer a migração sem downtime

A sequência menos arriscada: primeiro, mantenha o projeto Pages rodando. Crie os Workers novos em paralelo. Configure rotas que enviam tráfego para os Workers novos para paths específicos (começando pelos de menor risco, como webhooks ou rotas de admin). Valide o comportamento em produção com tráfego real antes de mover os paths principais. Só então desative as Pages Functions correspondentes.

Para o frontend, não migre assets de Pages para R2 antes de ter certeza de que o custo adicional está dentro do orçamento do projeto. Em muitos casos, a arquitetura híbrida — Pages para frontend e assets, Workers para jobs assíncronos e serviços especializados — é mais barata e igualmente flexível do que uma migração completa.

O que a migração realmente resolve

Cron triggers, múltiplos Workers com roteamento granular, staging com environments completamente isolados — esses são os problemas reais que justificam a migração. Se você está migrando por outra razão, vale revisar se não está trocando uma limitação por um custo maior.

A flexibilidade de Workers tem um preço operacional concreto: você assume o pipeline de CI, o preview deployment, e o custo de servir assets estáticos. Para serviços de backend puros sem assets significativos, esse custo é baixo. Para aplicações com frontend pesado e alto volume de tráfego estático, pode ser substancial.