Por que usamos o cf e não o Wrangler

Quem já publicou algo na Cloudflare conhece o Wrangler e o arquivo wrangler.jsonc. Este template não usa nenhum dos dois. Em vez disso, ele usa o cf, o novo CLI da Cloudflare. Este texto explica a troca.

O que é o cf

O cf é a ferramenta de linha de comando que a Cloudflare está construindo para substituir o Wrangler. Com ela você roda o ambiente local, compila, cria banco e publica:

npx cf dev       # servidor local
npx cf build     # compila
npx cf deploy    # publica

Há um ponto central: a configuração deixa de ser um JSON e vira código TypeScript.

O cloudflare.config.ts tipado

No lugar de um wrangler.jsonc cheio de textos soltos, você escreve:

import { bindings, defineConfig } from 'cf/config'

export default defineConfig({
  worker: {
    name: 'meu-app',
    env: {
      DB: bindings.d1({ name: 'meu-app-db', id: '...' }),
      BETTER_AUTH_SECRET: bindings.secret(),
    },
  },
})

Como é TypeScript, o editor completa as opções e acusa erro de digitação na hora. Os bindings declarados aqui geram os tipos do env, na pasta .cloudflare/types, e o seu código passa a saber que env.DB existe e é um D1.

O que muda em relação ao Wrangler

Assunto	Wrangler	cf
Arquivo de config	`wrangler.jsonc`	`cloudflare.config.ts`
Tipos dos bindings	`wrangler types`	`cf workers types`
Ambientes	`--env staging`	`--mode staging`
Segredos no deploy	`wrangler secret put`	`cf deploy --secrets-file`
Migrations de Durable Object	bloco `migrations`	`exports.durableObject(...)`

Os conceitos continuam os mesmos (Worker, D1, R2, Durable Objects). Muda o jeito de declarar e de chamar.

Por que não misturar os dois

Parece inofensivo deixar um wrangler.jsonc ao lado, "só por garantia". Não faça isso. Duas fontes de configuração significam duas verdades: você muda o ID do banco em um arquivo, esquece o outro, e o deploy vai para um lugar diferente do que o desenvolvimento local usa. Ferramentas e assistentes de IA também ficam confusos sobre qual arquivo manda.

Por isso o template não instala o Wrangler e a regra é simples: se precisa mudar a configuração, mude o cloudflare.config.ts.

O que significa estar em beta

O cf e o plugin do Vite que o acompanha ainda estão em versão beta. Na prática:

Comandos e opções podem mudar de uma versão para outra.
Podem existir bugs que a documentação ainda não registra.
Por isso as versões estão fixadas no package.json, sem o ^, e só devem ser atualizadas de propósito.

Antes de subir a versão, leia o changelog, rode a checagem de tipos, o build e o cf deploy --dry-run. Se algo quebrar, você volta para a versão anterior sem susto.

Conclusão

A troca traz configuração tipada e um fluxo único do código ao deploy. O preço é aceitar um beta. Se você precisa de estabilidade máxima hoje, conheça o risco antes de decidir, e mantenha as versões travadas.