Como dar funções dinâmicas a um site HTML com APIs e Cloudflare Workers

O que é dinâmico num site e o que não é

Dinâmico é tudo que muda conforme quem acessa ou o que a pessoa envia. Texto institucional, foto, preço fixo e página de serviço são estáticos. Envio de formulário, resultado de busca e área logada são dinâmicos.

Na prática, a maior parte de um site de empresa é estática. Por isso a arquitetura HTML mais Worker funciona: 95 páginas fixas e uma função para o formulário. O conceito completo de site sem servidor está em sites estáticos.

Como funciona um Worker

O Worker tem uma função chamada fetch, que a Cloudflare chama sempre que chega uma requisição HTTP. Ela recebe o pedido, o objeto env com variáveis e segredos, e devolve uma resposta. O exemplo mínimo da documentação oficial é este:

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  },
};

Para criar o projeto, a Cloudflare indica o comando abaixo. Ele usa o Wrangler, a ferramenta de linha de comando da Cloudflare.

npm create cloudflare@latest -- meu-worker
npx wrangler dev
npx wrangler deploy

O wrangler dev roda o Worker no seu computador, em localhost:8787. O wrangler deploy publica a versão na Cloudflare, por padrão num subdomínio workers.dev. Deploy é o nome que se dá à publicação de uma versão nova.

Worker ou Pages Function: qual usar

Se o site já está na Cloudflare Pages, o caminho mais simples é a Pages Function. Você cria uma pasta functions no projeto e cada arquivo vira uma rota. A documentação dá o exemplo: functions/helloworld.js responde em /helloworld.

Se a requisição não bate com nenhuma função, a Pages entrega o arquivo estático do mesmo caminho. Assim, HTML e função convivem no mesmo repositório do GitHub.

O Worker avulso faz sentido quando a função atende mais de um site ou quando você quer configurar tudo pelo Wrangler. O Worker também pode servir arquivos estáticos: a pasta indicada em assets no arquivo de configuração é entregue sem executar o código.

{
  "name": "meu-site",
  "main": "src/index.js",
  "assets": { "directory": "./dist", "binding": "ASSETS" }
}

Exemplo: formulário de contato com Pages Function

O formulário HTML aponta para a rota da função. O navegador envia os campos e a função decide o que fazer com eles.

<form action="/api/contato" method="post">
  <label>Nome <input name="nome" required></label>
  <label>E-mail <input name="email" type="email" required></label>
  <label>Mensagem <textarea name="mensagem" required></textarea></label>
  <button type="submit">Enviar</button>
</form>

A função fica em functions/api/contato.js. Ela lê os campos, faz uma validação básica e repassa para um serviço de e-mail ou planilha.

export async function onRequest(context) {
  if (context.request.method !== "POST") {
    return new Response("Método não permitido", { status: 405 });
  }
  const dados = await context.request.formData();
  const nome = String(dados.get("nome") || "").slice(0, 100);
  const email = String(dados.get("email") || "").slice(0, 200);
  if (!nome || !email.includes("@")) {
    return new Response("Preencha nome e e-mail", { status: 400 });
  }
  // aqui entra a chamada ao serviço de e-mail, usando context.env.CHAVE_EMAIL
  return Response.redirect(new URL("/obrigado/", context.request.url), 303);
}

1. Crie a pasta functions/api no projeto da Pages.
2. Salve o código acima como contato.js.
3. Cadastre a chave do serviço de e-mail como segredo.
4. Teste localmente, enviando o formulário com e sem os campos.
5. Faça o push para o GitHub e confira o deploy automático.

O MundoBlá recebe uma comissão da HostGator quando você contrata a hospedagem pelo nosso link, sem custo extra para você. Se o site terá formulário com função ou só botão de WhatsApp, isso é combinado no WhatsApp antes de começar.

Segredos e variáveis de ambiente

Segredo é um valor sensível, como chave de API ou senha, guardado criptografado na Cloudflare. A documentação diz que, depois de salvo, o valor não aparece mais no Wrangler nem no painel. Variável comum (vars) fica em texto aberto e não serve para dado sensível.

Você cadastra o segredo com um comando ou pelo painel, em Workers & Pages, Settings, Variables and Secrets.

npx wrangler secret put CHAVE_EMAIL

No código, o segredo aparece em env.CHAVE_EMAIL, ou context.env na Pages Function. Para testar no computador, crie o arquivo .dev.vars ao lado da configuração do Wrangler:

CHAVE_EMAIL="valor-de-teste"

A própria Cloudflare recomenda colocar .dev.vars e .env no .gitignore. Esse é o erro mais comum em site estático: chave de API dentro do JavaScript público ou enviada ao GitHub. A página segurança de sites estáticos aprofunda os cuidados.

Consumir uma API sem expor a chave

Quando o site precisa de dado externo, como cotação ou CEP, o Worker funciona como intermediário. O navegador pede ao Worker, o Worker chama a API com a chave e devolve só o resultado.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const cep = (url.searchParams.get("cep") || "").replace(/\D/g, "");
    if (cep.length !== 8) return new Response("CEP inválido", { status: 400 });
    // API_URL é o endereço da API, guardado como variável do Worker
    const r = await fetch(`${env.API_URL}/cep/${cep}`, {
      headers: { Authorization: `Bearer ${env.CHAVE_API}` },
    });
    return new Response(await r.text(), {
      headers: { "content-type": "application/json" },
    });
  },
};

Esse padrão também evita o erro de CORS, que acontece quando o navegador bloqueia a chamada direta a outro domínio. Cada chamada que o Worker faz para fora conta como subrequisição. Pela página de limites, o plano grátis permite 50 por execução.

Proteger formulário contra robôs com Turnstile

Turnstile é a alternativa da Cloudflare ao CAPTCHA, que funciona sem obrigar o visitante a resolver desafio. O widget no HTML gera um token. O Worker confere esse token antes de aceitar o envio.

A conferência é um POST para o endereço challenges.cloudflare.com/turnstile/v0/siteverify com dois campos obrigatórios: secret, a chave secreta do widget, e response, o token vindo do navegador. O IP do visitante é opcional. Sem essa etapa no servidor, o robô ignora a proteção.

Limites e preço do Workers

Os números abaixo vêm das páginas de preços e limites da Cloudflare, abertas em 5 de novembro de 2026. Confira antes de dimensionar um projeto, porque mudam com o tempo.

O ponto que mais pesa para site HTML: requisição a arquivo estático é grátis e ilimitada, nos dois planos. Só conta a requisição que executa código. A página de preços das Pages Functions confirma que elas são cobradas como requisições de Workers e que o limite diário do plano grátis zera à meia-noite UTC.

Para a conta completa de domínio, hospedagem e ferramentas, veja quanto custa manter um site com HTML e Cloudflare.

Quando Workers não é a melhor saída

Workers resolve bem funções curtas. Sistema com cadastro de clientes, estoque, pagamento e relatório pede banco de dados e regra de negócio maior. Para isso existem os bancos e filas da própria Cloudflare, ou um servidor tradicional. Leia sites sem banco de dados para ver até onde dá para ir sem banco.

Se o site é um WordPress com loja e área de membros, mudar tudo para Workers costuma custar mais do que manter o painel bem cuidado. A comparação honesta está em alternativas ao WordPress.

Se você chegou agora, a resposta curta sobre o Mundo Criação de Sites organiza o caminho, e a resposta sobre GitHub para sites mostra onde guardar o código. Dúvidas de outros assuntos têm resposta na página inicial.

Para ver a arquitetura inteira, volte ao guia Web livre: HTML, GitHub e Cloudflare.

Em outros Mundos

Para aprender o JavaScript que o Worker usa, passe pelo Mundo Programação. Notícias e guias de ferramentas digitais estão no Mundo Tecnologia.