Configurar o Modo de Integração no Cloudflare Workers, Next.js ou Caddy

Esta página mostra como conectar um domínio no Integration Mode nas três plataformas que têm uma integração open-source pronta. Cada uma serve os redirecionamentos, links curtos e links de QR code que você gerencia no RedirHub a partir de um arquivo de regras, sem precisar de um novo deploy a cada mudança, e registra cada redirecionamento nas suas análises.

Antes de começar: o endereço das regras e a chave#

1. No painel, adicione o domínio em Hostnames e escolha Connect through your own platform.
2. Escolha sua plataforma. O painel mostra o endereço das regras para o domínio e a chave de integração do seu workspace, além de um prompt com ambos já preenchidos que você pode colar em um agente de codificação com IA (Claude, Cursor, ChatGPT e outros) em vez de seguir os passos abaixo manualmente.
3. Armazene a chave como segredo ou variável de ambiente. O endereço das regras não é segredo, mas não o publique.

Depois de fazer o deploy, a primeira resposta em /_redirhub/check conecta o domínio. O painel verifica a cada 15 minutos, ou imediatamente com Check now.

Cloudflare Workers#

Um Worker na frente da sua origem serve os redirecionamentos e encaminha todas as outras solicitações. Código-fonte e opções completas: redirhub/cloudflare-redirects.

bashnpm install @redirhub/cloudflare-redirects

Criar src/index.ts:

typescriptimport { createWorker } from '@redirhub/cloudflare-redirects'

interface Env {
  ACME_RULES_URL: string
  ACME_INTEGRATION_KEY: string
}

export default createWorker<Env>({
  settings: (env) => ({ rulesUrl: env.ACME_RULES_URL, key: env.ACME_INTEGRATION_KEY }),
})

Defina uma rota para o hostname e o endereço das regras em wrangler.toml (o painel mostra os nomes exatos das variáveis para o seu domínio):

tomlname = "shop-redirects"
main = "src/index.ts"
compatibility_date = "2026-11-01"
routes = [{ pattern = "shop.example.com/*", zone_name = "example.com" }]

[vars]
ACME_RULES_URL = "https://rules.example.com/…/TOKEN.txt"

Adicione a chave como um segredo e faça o deploy:

bashnpx wrangler secret put ACME_INTEGRATION_KEY
npx wrangler deploy

• A rota deve abranger todos os caminhos do hostname, incluindo /_redirhub/check.
• Regras curinga funcionam: quando sua origem responde 404, o Worker redireciona em vez disso.
• Relatórios de 404 funcionam: os 404 da sua origem são reportados quando Reportar páginas 404 está ativado para o hostname.

Next.js (Vercel ou self-hosted)#

Os redirecionamentos são executados no seu proxy (Next.js 16) ou middleware (Next.js 15 e anteriores), antes das suas páginas. Código-fonte e opções completas: redirhub/nextjs-redirects.

bashnpm install @redirhub/nextjs-redirects

Adicione o endereço das regras e a chave como variáveis de ambiente (nas configurações do projeto no Vercel, ou .env.local localmente). Nunca prefixe a chave com NEXT_PUBLIC_. Em seguida, crie proxy.ts (ou middleware.ts com export function middleware no Next.js 15 e anteriores):

typescriptimport type { NextFetchEvent, NextRequest } from 'next/server'
import { createProxy } from '@redirhub/nextjs-redirects'

const redirects = createProxy({
  rulesUrl: process.env.ACME_RULES_URL,
  key: process.env.ACME_INTEGRATION_KEY,
})

export async function proxy(request: NextRequest, event: NextFetchEvent) {
  const answer = await redirects(request, event)
  if (answer) return answer
  // … sua própria lógica de proxy, ou nada
}

• Chame-o primeiro, antes das reescritas e do tratamento de locale.
• O matcher deve permitir /_redirhub/check e os caminhos pelos quais você faz o redirecionamento passar. Um matcher que ignora todos os caminhos com um ponto também ignora regras como /old.html.
• Os redirecionamentos em next.config são executados antes do proxy, então podem sobrepor as suas regras.
• O proxy é executado antes da página e nunca vê se o seu app responde 404, então regras curinga e relatórios de 404 não são servidos ali. Para adicionar ambos, use createRedirects() e seu afterSite(), onde você vê a resposta final, por exemplo em um route handler (veja o README).

Caddy#

Um módulo Caddy v2 para seus próprios servidores. Um único Caddy pode servir todos os seus domínios de integração a partir de um endereço de regras do Workspace, e ele pode emitir certificados HTTPS sob demanda apenas para os nomes de host nas suas regras. Código-fonte e opções completas: redirhub/caddy-redirects.

Compile o Caddy com o módulo:

bashxcaddy build --with github.com/redirhub/caddy-redirects

Para o Caddy, copie o endereço de regras do Workspace do painel da chave de integração em vez do endereço por domínio. Depois, adicione o manipulador ao seu Caddyfile:

text{
	on_demand_tls {
		permission redirects
	}
}

https:// {
	tls {
		on_demand
	}
	redirects {
		rules_url https://rules.rediredge.com/abc123/TOKEN.txt
		key {env.REDIRHUB_INTEGRATION_KEY}
	}
	reverse_proxy localhost:8080
}

• Defina REDIRHUB_INTEGRATION_KEY no ambiente do Caddy e recarregue o Caddy.
• As alterações chegam em um ou dois segundos por push, com polling como alternativa. As últimas regras válidas são mantidas em disco, então uma reinicialização redireciona imediatamente.
• Regras catch-all funcionam quando o restante da rota responde 404. Atrás de try_files com um fallback (um aplicativo de página única), o site nunca responde 404, então o catch-all nunca é acionado.
• Os relatórios de 404 seguem a opção Report 404 pages de cada hostname. Com report_404 all, cada 404 do bloco do site é reportado, mesmo para hostnames que você ainda não adicionou ao RedirHub.

Depois de implantar#

• Abra o domínio em Hostnames e clique em Verificar agora. O status deverá mudar para Conectado.
• Teste uma regra numa janela privada ou com curl -I.
• Se o domínio permanecer em Aguardando ou um redirecionamento não for acionado, consulte Solução de problemas do Modo de Integração.