Quando publiquei a primeira versão deste artigo, em 2022, a Cloudflare ainda usava a sintaxe de Service Worker em muitos exemplos. A plataforma evoluiu desde então. Hoje, Module Workers, Wrangler e bindings formam o fluxo recomendado.
O Cloudflare Workers permite executar código serverless na rede global da Cloudflare. Assim, você pode criar APIs, redirects, middleware e aplicações completas sem administrar servidores.
Neste guia, vamos entender como o runtime funciona. Além disso, criaremos um Worker com a sintaxe atual.
O que é Cloudflare Workers?
Cloudflare Workers é uma plataforma serverless para executar código na rede da Cloudflare. Em vez de manter uma máquina virtual ou um container por aplicação, você envia o código para a plataforma.
A Cloudflare distribui esse código pela sua rede global. Quando uma requisição chega, o runtime executa o Worker conforme a rota configurada.
Se o conceito ainda for novo, vale começar pelo artigo sobre o que é serverless. Também publiquei uma introdução sobre como funciona a CDN da Cloudflare.
O runtime usa o motor JavaScript V8, também presente no Chromium e no Node.js. Além disso, oferece APIs conhecidas da web, como Request, Response, fetch, Streams e Web Crypto.
Porém, Cloudflare Workers não é um processo Node.js tradicional. A plataforma oferece compatibilidade com várias APIs do Node por meio da flag nodejs_compat. Ainda assim, você deve confirmar o suporte de cada pacote antes de usá-lo.
Como Cloudflare Workers funciona?
Três conceitos ajudam a entender a plataforma: isolates, computação por requisição e execução distribuída.
Isolates do V8
O V8 executa cada aplicação em um isolate. Um isolate é um contexto leve e isolado de memória.
Esse modelo permite que um processo do runtime hospede muitas aplicações. Como resultado, a plataforma evita o custo de iniciar uma máquina virtual para cada função.
Os isolates também começam mais rápido que processos baseados em VMs ou containers. No entanto, eles não permanecem ativos para sempre. A plataforma pode removê-los por limites de recursos, atualizações ou decisões do runtime.
Por isso, nunca trate a memória global como armazenamento persistente.
Computação por requisição
A sintaxe atual usa ES modules. O arquivo exporta um objeto com os handlers dos eventos que o Worker processa.
Um Worker HTTP básico usa o handler fetch:
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (url.pathname === "/api/hello") {
return Response.json({
message: "Olá do Cloudflare Workers!",
});
}
return new Response("Rota não encontrada", {
status: 404,
});
},
};Code language: JavaScript (javascript)O handler recebe três argumentos:
request: contém a requisição HTTP.env: expõe variáveis, secrets e bindings configurados.ctx: controla tarefas ligadas ao ciclo de vida da execução.
O handler deve retornar uma instância de Response ou uma Promise que resolva para uma resposta.
O exemplo antigo com addEventListener ainda funciona. Contudo, a Cloudflare marcou a sintaxe de Service Worker como deprecated. Portanto, use Module Workers em projetos novos.
CPU time não é o mesmo que duração
O runtime mede o tempo em que a CPU executa o seu código. Esperar uma chamada de rede com fetch, por exemplo, não consome CPU time durante a espera.
A duração total da requisição inclui rede, armazenamento e outras operações assíncronas. Para requisições HTTP, não existe um limite rígido de duração enquanto o cliente continua conectado.
Se uma tarefa puder terminar depois da resposta, use ctx.waitUntil():
export default {
async fetch(request, env, ctx) {
const response = Response.json({ status: "ok" });
ctx.waitUntil(registrarEvento(env, request));
return response;
},
};
async function registrarEvento(env, request) {
// Envie analytics ou atualize um cache aqui.
}Code language: JavaScript (javascript)Use waitUntil apenas quando a resposta não depender do resultado. Caso contrário, use await antes de retornar.
Como criar seu primeiro Cloudflare Worker
A ferramenta oficial de linha de comando se chama Wrangler. O C3, ou Create Cloudflare CLI, gera a estrutura inicial.
No terminal, execute:
npm create cloudflare@latest -- meu-primeiro-workerCode language: CSS (css)Durante a configuração, escolha um exemplo Hello World e o template Worker only. Em seguida, abra a pasta criada:
cd meu-primeiro-workerPara iniciar o ambiente local:
npx wrangler devO Wrangler abre um servidor em http://localhost:8787. Agora você pode editar src/index.js e validar o resultado localmente.
Quando o código estiver pronto, faça o deployment:
npx wrangler deployO projeto recebe um endereço *.workers.dev. Você também pode conectar uma rota ou um custom domain.
O arquivo wrangler.jsonc guarda a configuração do projeto. Entre outras opções, ele define o arquivo principal e a compatibility_date.
A Cloudflare recomenda usar a data atual em projetos novos. Depois, atualize essa data com testes para adotar mudanças recentes do runtime.
Como trabalhar com estado e armazenamento
Não armazene dados de usuário em variáveis globais. Duas requisições podem usar o mesmo isolate, isolates diferentes ou localidades diferentes.
Este exemplo é inseguro:
let usuarioAtual;
export default {
async fetch(request) {
usuarioAtual = request.headers.get("X-User-Id");
return Response.json({
usuario: usuarioAtual,
});
},
};Code language: JavaScript (javascript)Uma requisição seguinte pode encontrar o valor anterior. Além disso, o dado desaparece quando o isolate é removido.
Passe os dados pelas funções e escolha um serviço de armazenamento adequado:
- Workers KV: configurações e dados lidos com frequência quando a consistência eventual é aceitável.
- R2: imagens, arquivos e outros objetos grandes.
- D1: dados relacionais consultados com SQL.
- Durable Objects: estado consistente, coordenação e aplicações em tempo real.
Esses serviços chegam ao código por meio de bindings. Um binding funciona como permissão e API. Dessa forma, você não precisa expor uma chave para acessar um recurso da própria conta.
Limites do Cloudflare Workers
A plataforma impõe limites de CPU, memória, tamanho do Worker e subrequests. Esses valores variam entre os planos.
Em julho de 2026, o plano gratuito inclui:
- 100 mil requisições por dia;
- 10 ms de CPU por requisição HTTP;
- 128 MB de memória;
- 50 subrequests por execução;
- bundle comprimido de até 3 MB.
O plano pago amplia vários desses limites. Entretanto, os valores podem mudar. Consulte sempre a página oficial de limites do Workers antes de planejar uma aplicação.
Também não confunda CPU time com wall time. Uma chamada externa lenta pode aumentar a duração sem usar CPU durante toda a espera.
Quando usar Cloudflare Workers?
Cloudflare Workers funciona bem para tarefas que precisam ficar próximas da entrada da aplicação:
- criar APIs e endpoints;
- validar autenticação;
- adicionar ou alterar headers;
- implementar redirects;
- personalizar respostas;
- fazer proxy para uma API;
- aplicar regras de cache;
- processar webhooks;
- servir aplicações full-stack.
Para sites estáticos com integração Git, veja também como funciona o Cloudflare Pages. Workers e Pages podem trabalhar juntos por meio de Pages Functions e bindings.
Cuidados antes de adotar a plataforma
O modelo distribuído traz velocidade e escala. Contudo, ele também exige algumas decisões de arquitetura.
Primeiro, valide as APIs disponíveis no runtime. Nem todo pacote criado para Node.js funcionará sem ajustes.
Depois, escolha o armazenamento pela consistência necessária. Workers KV, por exemplo, tem consistência eventual. Portanto, ele não substitui Durable Objects em cenários que exigem coordenação forte.
Por fim, acompanhe CPU time, subrequests e observabilidade. Uma função pequena pode chamar vários serviços e alcançar limites antes do esperado.
Conclusão
Cloudflare Workers combina um runtime baseado em V8 com a rede global da Cloudflare. Assim, você pode executar código serverless sem manter servidores ou containers.
O exemplo moderno usa Module Workers, recebe request, env e ctx, e retorna uma Response. Para persistir dados, use bindings e os serviços adequados.
Comece com um endpoint simples, teste com Wrangler e faça o deployment em workers.dev. Depois, evolua a aplicação conforme a necessidade de armazenamento, consistência e observabilidade.
Deixe um comentário