Como publicar uma página no Cloudflare Workers

A pasta com a página pronta existe, o link ainda não. Vamos publicar no Cloudflare Workers e passar o procedimento para o Claude Code: criamos um skill com o qual publicar e atualizar se resume a um pedido curto.

1. O que é o Cloudflare Workers para conteúdo estático

A palavra Workers soa como "programas que rodam no servidor", e isso é verdade. Mas não é tudo: dá para anexar a um worker uma pasta de arquivos, e aí o servidor simplesmente os entrega, como uma hospedagem comum. Não se escreve nenhuma linha de código nisso.

Para uma página feita de HTML, CSS e imagens, esse modo basta. Na documentação essa pasta se chama static assets, ativos estáticos, e nas configurações do projeto ela ocupa exatamente um campo, o do caminho.

O Cloudflare entrega os arquivos pela sua própria rede de servidores e faz cache deles mais perto dos visitantes.

2. Quanto custa

As requisições a arquivos estáticos são gratuitas e sem limite de quantidade. Essa é uma condição do plano, não uma promessa de que ninguém conta as visitas.

Então de onde vem aquele número conhecido - 100.000 requisições por dia? É o limite de chamadas a um Worker script, aquele mesmo programa no servidor. Uma página que só tem uma pasta anexada não tem script e não entra nesse contador.

O caminho de cima no esquema é o que a nossa página segue: o arquivo é entregue sem chamar um programa do lado do servidor. O de baixo entra em jogo se depois for adicionado um Worker script.

O plano gratuito tem limites, sim, mas são sobre outra coisa - o tamanho do que se publica:

Para uma página com uma dezena de imagens, esses limites costumam bastar. Antes de um projeto grande, confira as condições atuais do Cloudflare: os limites podem mudar. 25 MB por arquivo, aliás, parece generoso até o primeiro vídeo.

3. A conta

O cadastro em cloudflare.com é o de sempre: email e senha, e depois um email de confirmação. Não é preciso cartão para o plano gratuito. Também não é preciso adicionar um domínio próprio - o serviço vai sugerir isso, mas a sugestão é da outra metade do produto, a de proteger e acelerar sites que já existem.

Depois de entrar, a seção que interessa se chama "Workers & Pages", e não fica logo à vista: no menu à esquerda primeiro o grupo Build, dentro dele Compute, e só lá dentro - "Workers & Pages". O painel muda de layout de vez em quando, então se essa seção não estiver nesse caminho, procure pelo nome: a busca no canto superior esquerdo abre com Ctrl + K. As duas palavras no nome são dois produtos do Cloudflare; o(a) senhor(a) precisa da primeira metade, Workers, e vai parar lá automaticamente, sem escolher nada de propósito.

Mais uma coisa vai aparecer no primeiro deploy: o Cloudflare vai pedir para escolher um nome de subdomínio para a conta. Todos os seus projetos vão morar nele, e o endereço se forma de duas partes - o nome do projeto mais o seu subdomínio:

my-landing.example-account.workers.dev
|          |               |
|          |               domínio compartilhado do Cloudflare
|          subdomínio da sua conta
nome do projeto

mudar esse nome depois dá trabalho, então é melhor não digitar a primeira coisa que vier à cabeça.

4. O primeiro deploy

Primeiro, uma olhada rápida em como a publicação funciona no painel. É um passeio opcional pelo serviço: se preferir já configurar o deploy pelo agente e manter um único endereço, pule para a preparação abaixo.

landing/          <- essa é a pasta que entregamos
  index.html      <- página principal, o nome é obrigatório
  wrangler.jsonc  <- o agente cria antes do primeiro deploy
  style.css
  img/
    hero.png

Antes de publicar, confira o conteúdo da pasta escolhida: os arquivos dela vão ficar públicos. Tire de lá arquivos pessoais e rascunhos que não eram para mostrar.

Na mão, pelo painel

A seção de projetos tem um botão que abre um projeto novo. Depois vão pedir que o(a) senhor(a) entregue os arquivos: dá para escolher um arquivo só, ou a pasta inteira. Enviou, confirmou - o Cloudflare organizou tudo do lado dele e devolveu um link. Os nomes dos botões e a ordem das telas mudam aqui mais rápido do que saem artigos, então siga o sentido, não os rótulos: abrir um projeto, entregar os arquivos, receber um endereço.

Abra o endereço recebido,https://…workers.dev, e confira a página e as imagens. Dá para fazer isso no mesmo computador. Um celular ajuda a confirmar que a página abre e fica bem no visual mobile.

Publicar pelo painel não deixa nenhum config local. O skill do nosso exemplo não vincula sozinho uma pasta a um projeto assim: sem config, ele vai inventar um nome novo e um segundo endereço. O Cloudflare permite atualizar um Worker já existente pelo Wrangler, mas para isso é preciso montar à parte um config com o nome dele.

O que é preciso para o agente fazer isso

Para as próximas publicações, vamos montar um skill. A preparação é feita uma vez só, no seu computador.

Não são necessários muitos programas. A conta o(a) senhor(a) já tem, falta o Node.js - confira com o comando node -v, e se o comando não for encontrado, instale-o primeiro. O próprio wrangler não precisa ser instalado: o npx baixa uma versão nova sozinho, na hora que precisar.

O segundo passo do esquema é o login, e vale resolver isso agora mesmo, antes de qualquer outra coisa:

npx wrangler login    # abre o navegador, com um botão de confirmação

Rode o comando no terminal. Se esse passo faltar, todo o procedimento vai travar nele logo na primeira execução, e vai parecer um skill quebrado, embora o problema não esteja nele. Para conferir se deu certo, use o comando npx wrangler whoami - ele mostra com qual conta o login foi feito.

Para esse caminho, o login pelo navegador já basta. O token de API é explicado na continuação opcional, no final.

O terceiro passo do esquema, npx wrangler deploy, é o que o agente vai rodar a partir da pasta da página. Primeiro damos a ele as regras de preparar o config e de publicar.

5. Seu próprio skill de deploy

Enquanto a página é uma só, um pedido no chat resolve. Mas basta criar uma segunda, uma terceira, uma décima - e toda vez é preciso explicar a mesma coisa para o agente: qual pasta pegar, como nomear o projeto, o que fazer com o arquivo de configuração. Na terceira vez, isso já cansa.

O que o skill precisa saber fazer

Cinco passos, e cada um resolve um problema concreto, não está ali só para completar:

1. Pegar a pasta indicada e confirmar que o index.html está na raiz dela. Uma checagem barata que pega o erro mais comum antes do deploy, não depois.
2. Definir o nome do projeto - deduzindo-o do nome da pasta, em vez de perguntar toda vez.
3. Ver se dentro da pasta, ao lado do index.html, existe um arquivo wrangler.jsonc. Se não - criar; se sim - pegar o nome dali e não reescrever nada nele.
4. Rodar o deploy a partir dessa pasta, mostrando o comando antes de rodar.
5. Devolver o endereço público e lembrar de conferir a página e as imagens nele.

O nome do projeto vem da pasta

Essa é a decisão principal de todo o procedimento, e é justamente ela que não dá para deixar o agente improvisar. Se a regra não define o nome, o agente vai inventar um sozinho - e da próxima vez vai inventar outro. O resultado é um segundo projeto com outro endereço, e o primeiro fica ali parado.

A regra é simples: o nome da pasta é o nome do projeto. No nome do worker só podem entrar letras latinas minúsculas, números e hífen, então todo o resto - pontos, espaços, underscores - vira hífen, e no final entra um sufixo curto, quatro caracteres aleatórios:

landing/                 ->  landing-42c2
my.first.page/           ->  my-first-page-8e10
portfolio-2026/          ->  portfolio-2026-b7a3

O sufixo existe para que duas pastas com o mesmo nome em projetos diferentes não ocupem um só endereço. Ele é gerado uma única vez, na hora de criar o arquivo de configuração, e obrigatoriamente por um comando, não da cabeça do agente: senão ele pega o sufixo do exemplo, e todo mundo que leu o mesmo artigo acaba com o mesmo sufixo. Depois disso, o sufixo sempre é lido do config. É exatamente por isso que o skill primeiro olha o config existente e só depois escreve alguma coisa.

Quem escreve o arquivo de configuração é o agente

No wrangler.jsonc o agente grava o nome do projeto e as configurações de publicação, para que o deploy rode sem perguntas no terminal. O config fica ao lado do index.html, então o caminho para os arquivos nele é um ponto, "essa mesma pasta":

{
  "name": "landing-42c2",
  "compatibility_date": "2026-09-07",
  "assets": { "directory": "." }
}

O campo compatibility_date escolhe o comportamento da plataforma que valia na data indicada. Num config novo, o agente coloca a data atual, como recomenda a documentação do Cloudflare; numa publicação seguinte, mantém a data antiga.

Não vale colocar o config um nível acima, ao lado da pasta: o nome do arquivo é fixo, num mesmo diretório só pode existir um, e a segunda pasta vai sobrescrever o config da primeira ou sair publicada com o nome dela. Dentro da pasta, cada projeto é autossuficiente, e o deploy roda direto de lá.

Um efeito colateral dessa organização: o config fica na mesma pasta que a página, então vai junto para a hospedagem e fica acessível pelo link. Não há segredo nele - nome, data e um ponto -, e quem se incomodar coloca ao lado um arquivo .assetsignore e lista ali o que não publicar.

Três regras que vale deixar explícitas na tarefa, porque o agente não vai adivinhar:

• não tem arquivo - criar, mostrando o que foi gravado;
• tem arquivo - manter o nome e a data como estão, mesmo que a data de hoje seja outra;
• reescrever o arquivo só quando o conteúdo realmente muda.

Quatro pedidos que vale a pena guardar à mão

O primeiro é a própria tarefa do skill. É mais longo que os outros, porque é a única vez em que o procedimento é descrito inteiro:

Monte um skill para fazer deploy de páginas estáticas no Cloudflare Workers.
Coloque em .claude/skills/ deste projeto.
No final, mostre o caminho do SKILL.md criado e a forma de chamar o skill manualmente.

Primeiro leia a documentação atual do Cloudflare sobre Workers
e static assets: os comandos e os campos do config podem ter mudado.
Se algo na descrição abaixo divergir da documentação, me avise,
não reescreva por conta própria.

Na description do skill, liste as frases que devem acioná-lo,
pelo menos: "publique a pasta", "publique de novo", "faça o deploy no Cloudflare".

Procedimento: pego a pasta, confiro que index.html está na raiz.
Deduzo o nome do projeto a partir do nome dessa pasta: nele ficam só
letras latinas minúsculas, números e hífen, todo o resto (espaços,
underscores, maiúsculas, caracteres não latinos) eu troco por hífen.
No final acrescento, depois de um hífen, um sufixo de quatro caracteres.
Não invento o sufixo, eu pego com o comando:
node -e "console.log(crypto.randomUUID().slice(0,4))"
O config wrangler.jsonc fica dentro da pasta publicada, ao lado
do index.html, e assets.directory nele é igual a ".".
Se não houver config - eu crio: name, compatibility_date,
assets.directory. Para um compatibility_date novo, pego a data atual
no formato YYYY-MM-DD. Mostro o que gravei.
Se já houver config - pego o nome e a data dali e não reescrevo.
Só reescrevo o arquivo quando o conteúdo realmente muda.
Se houver config, mas assets.directory apontar para outra pasta
ou o config tiver um campo main - eu paro e aviso, não faço o deploy.
Se pedirem para publicar de novo e não houver config na pasta - eu paro
e pergunto, não crio um projeto novo.
Deploy: npx wrangler deploy a partir da pasta do projeto. Mostro o comando antes de rodar.
Na resposta devolvo o endereço público e lembro de conferir nele
a página e as imagens. Numa atualização, o endereço deve continuar o mesmo.
Se não houver Node.js ou a autenticação não estiver feita - eu digo isso,
sem tentar contornar.
Se a conta ainda não tiver um subdomínio workers.dev - eu digo isso:
o deploy não interativo falha nesse caso.

Depois de criado, abra o arquivo que o agente mostrou, .claude/skills/<nome>/SKILL.md: as regras acima devem estar lá. Antes do segundo pedido, chame explicitamente o skill criado da forma que o agente mostrou. Se o skill não for encontrado, peça para conferir o caminho e a disponibilidade dele no projeto atual.

O segundo é a checagem antes de agir. Útil antes do primeiro deploy de uma pasta, quando se quer ver o plano antes de qualquer coisa ir para o ar; se houver várias pastas, peça isso para cada uma:

Não crie nem mude nenhum arquivo, não rode o wrangler. Só mostre
o que você vai fazer com a pasta landing: qual nome de projeto,
qual config vai gravar, qual comando vai rodar.

Uma ressalva: o sufixo só aparece no momento de gravar o config, então para uma pasta que ainda não tem config, o nome no plano e o nome na execução real podem não bater. Todo o resto bate.

O terceiro e o quarto são os pedidos de verdade, o motivo de tudo isso:

Publique a pasta landing no Cloudflare Workers.

Corrigi o index.html em landing. Publique de novo no Cloudflare Workers.

Depois da primeira publicação, abra o link recebido e confira o texto e as imagens. Em seguida, mude uma frase bem visível em landing/index.html e mande o quarto pedido. Atualize a página no mesmo endereço: a nova frase deve aparecer. Se o endereço mudou, peça ao agente para conferir o nome no config antes do próximo deploy.

Com isso o caminho principal está fechado: o skill foi criado, a página está publicada, e a atualização foi conferida no mesmo link. Antes de cada publicação, o que resta é escolher a pasta certa e olhar o comando do agente.

6. Cenários extras

Dá para não ler daqui em diante, enquanto não for preciso preparar várias pastas de uma vez ou rodar o deploy sem entrar pelo navegador.

Quando o procedimento não é mais suficiente

O skill em forma de instrução funciona bem enquanto as pastas são poucas, ou algumas dezenas. Depois disso, começa a atrapalhar o fato de o agente reler o procedimento toda vez e executá-lo na mão: em cinquenta pastas isso é lento e nem sempre sai igual.

Nesse ponto, o procedimento vira um script: ele percorre as pastas sozinho, escreve os configs, pula as que não mudaram e imprime um resumo. O skill não desaparece com isso - ele só passa a chamar o script em vez de escrever os configs na mão, e continua rodando o deploy por conta própria.

Escrever esse script também não é trabalho seu. O agente já tem uma descrição detalhada do procedimento - o seu skill -, então o pedido sai curto:

Escreva em Python um script que faça o mesmo que o meu skill de deploy
descreve, só que já para todas as pastas do projeto de uma vez.

Pega as pastas que têm index.html na raiz;
não entra em node_modules, .git e dist.
Para cada uma, monta o nome pela nossa regra e escreve o wrangler.jsonc
dentro da pasta.
Se já houver config - pega o nome e o compatibility_date dali,
e só reescreve o arquivo quando o conteúdo realmente mudou.
Se o config não puder ser lido - não mexe nele, avisa
e pula a pasta.
Por padrão só mostra o plano e não escreve nada;
a gravação acontece com uma flag explícita.
Preciso de um filtro para rodar só as pastas escolhidas.
O script só prepara os configs, não faz o deploy.
No final imprime uma tabela: pasta, nome do projeto, o que foi feito.
Se algo nessa descrição for ambíguo - pergunte, não invente por conta própria.

Mostrar o plano permite conferir a lista de pastas antes de gravar qualquer coisa. Manter o nome e a data protege os configs existentes de mudanças acidentais. O script em si só prepara as configurações; quem publica continua sendo o skill.

Token de acesso

No seu computador, o login já foi feito com npx wrangler login. O Wrangler guarda essa autenticação, e os comandos do agente também a usam.

Se precisar de uma execução automática sem entrar pelo navegador, ou de permissões mais restritas, aí entra o token de API. Dá para criar um no perfil: avatar, perfil, seção de tokens de API. O endereço direto é dash.cloudflare.com/profile/api-tokens.

O formulário de criação parece assustador: grupos de permissões, recursos, uns filtros. Na prática são quatro decisões, e metade dos campos dá para deixar como está.

1. Nome do token. Daqui a seis meses o(a) senhor(a) não vai lembrar para que ele serve, então escreva algo direto: "deploy de páginas do notebook", não "token 2".
2. Permissões. Não é preciso, nem recomendável, montar isso permissão por permissão. Na lista de modelos prontos existe Edit Cloudflare Workers - ele já reúne tudo o que a publicação precisa.
3. Recursos. Limite o token a uma única conta, exatamente aquela onde se publica. Mesmo que a conta seja uma só, escolha-a explicitamente: contas podem se multiplicar, e o token continua sendo o mesmo.
4. Tempo de vida e filtro de IP. Campos opcionais. Vale definir um prazo quando o token é para uma noite só ou para a máquina de outra pessoa; no trabalho comum, deixe como está.

Depois disso, coloque o token na variável de ambiente CLOUDFLARE_API_TOKEN, e a conta em CLOUDFLARE_ACCOUNT_ID. Variável de ambiente é uma configuração da sua máquina que os programas leem sozinhos; o wrangler vai achar as duas sem nenhuma intervenção. Como as variáveis funcionam e onde guardá-las direito é outra conversa; aqui basta saber que é um lugar, não uma linha na conversa.