Cloudflare Workers + CLI: Deploy de APIs JavaScript na Edge sem Docker, sem Kubernetes

O problema: sua API roda em uma região só e o deploy exige um PhD em YAML

Você tem uma API em Node.js. Ela roda em São Paulo (ou, pior, em us-east-1 porque era o default). O deploy envolve Docker, registry, Kubernetes ou algum PaaS que cobra por container idle. O cold start dói. O pipeline de CI/CD tem mais linhas de configuração do que a aplicação.

Cloudflare Workers resolve uma parte específica desse problema: APIs leves, stateless ou com estado simples (KV, Durable Objects), que rodam em mais de 300 pontos de presença, com cold start abaixo de 5ms, deploy em segundos via CLI. Não substitui um backend pesado com PostgreSQL e filas. Substitui o endpoint que valida webhook, o proxy que adiciona headers, a API de configuração que lê/grava flags, o rate limiter na borda.

Este post cobre o fluxo completo: setup do projeto, código da API, KV como storage, secrets, testes locais, deploy via Wrangler CLI e integração com CI/CD. Tudo rodável.

Wrangler CLI: o que faz e o que não faz

Wrangler é a CLI oficial da Cloudflare para Workers. Ela cria projetos, roda localmente (via Miniflare), faz deploy, gerencia secrets, namespaces KV e tail de logs em tempo real.

Capacidade	Wrangler CLI	Docker + K8s	Serverless (AWS Lambda)
Cold start típico	< 5ms	N/A (container quente)	100-500ms (Node.js)
Deploy time	5-15 segundos	minutos	30-60 segundos
Regiões	300+ PoPs automático	você escolhe	você escolhe
Storage integrado	KV, R2, D1, Durable Objects	externo	DynamoDB, S3
Custo em idle	zero (free tier: 100k req/dia)	container rodando	zero
Runtime	V8 isolates (não é Node.js)	qualquer	Node.js, Python, etc.
Limite de CPU time	10ms (free) / 30s (paid)	sem limite	15 min

A distinção de runtime importa: Workers rodam em V8 isolates, não em Node.js. Não há fs, não há child_process, não há node:net nativo. APIs da Web Platform (fetch, Request, Response, crypto, streams) estão disponíveis. Algumas APIs Node.js têm compatibilidade parcial via flag nodejs_compat.

Setup: do zero ao primeiro request local

Instale o Wrangler globalmente ou como devDependency (prefiro devDependency para fixar versão no time):

npm init -y
npm install --save-dev wrangler
npx wrangler --version

Crie o projeto com scaffold mínimo:

npx wrangler init api-edge --type javascript
cd api-edge

O arquivo wrangler.toml gerado é o centro de configuração. Ajuste para algo funcional:

name = "api-edge"
main = "src/index.js"
compatibility_date = "2024-12-01"

# Habilita APIs Node.js parciais quando necessário
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "production"

# KV namespace: crie antes com `wrangler kv namespace create CACHE_KV`
[[kv_namespaces]]
binding = "CACHE_KV"
id = "SEU_NAMESPACE_ID_AQUI"

A API: roteamento manual sem framework

Para APIs simples (3-10 rotas), adicionar um framework como Hono ou itty-router é válido. Para entender o que acontece por baixo, comece sem framework:

// src/index.js
// Workers usam a API de fetch da Web Platform, não http.createServer do Node.js
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const path = url.pathname;
    const method = request.method;

    // Roteamento explícito: sem regex, sem overhead de framework
    if (method === "GET" && path === "/health") {
      return Response.json({ status: "ok", region: request.cf?.colo });
    }

    if (method === "GET" && path === "/flags") {
      return handleGetFlags(env);
    }

    if (method === "PUT" && path.startsWith("/flags/")) {
      const flagName = path.split("/flags/")[1];
      return handleSetFlag(request, env, flagName);
    }

    return Response.json({ error: "not found" }, { status: 404 });
  },
};

async function handleGetFlags(env) {
  // KV list retorna chaves com prefixo: útil para agrupar dados por domínio
  const list = await env.CACHE_KV.lis

---

Leia o artigo completo em [https://www.vivodecodigo.com.br/infra/cloudflare-workers-cli-deploy-api-javascript-edge](https://www.vivodecodigo.com.br/infra/cloudflare-workers-cli-deploy-api-javascript-edge)