Configura el modo de integración en Cloudflare Workers, Next.js o Caddy

Esta página muestra cómo conectar un dominio en Integration Mode en las tres plataformas que tienen una integración de código abierto lista para usar. Cada una sirve las redirecciones, los enlaces cortos y los enlaces de códigos QR que gestionas en RedirHub desde un archivo de reglas, sin necesidad de redeplegar con cada cambio, y registra cada redirección en tu analítica.

Antes de empezar: la dirección de reglas y la clave#

1. En el panel, añade el dominio en Hostnames y elige Connect through your own platform.
2. Elige tu plataforma. El panel muestra la rules address para el dominio y la integration key de tu espacio de trabajo, además de una indicación con ambos campos completados que puedes pegar en un agente de codificación con IA (Claude, Cursor, ChatGPT y otros) en lugar de seguir los pasos de abajo manualmente.
3. Guarda la clave como secreto o variable de entorno. La dirección de reglas no es un secreto, pero no la publiques.

Después de desplegar, la primera respuesta en /_redirhub/check conecta el dominio. El panel comprueba cada 15 minutos, o de inmediato con Check now.

Cloudflare Workers#

Un Worker delante de tu origen sirve las redirecciones y pasa el resto de solicitudes sin cambios. Código fuente y opciones completas: redirhub/cloudflare-redirects.

bashnpm install @redirhub/cloudflare-redirects

Crear 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 }),
})

Configura una ruta para el hostname y la dirección de las reglas en wrangler.toml (el panel muestra los nombres exactos de las variables para tu dominio):

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"

Añade la clave como un secreto y despliega:

bashnpx wrangler secret put ACME_INTEGRATION_KEY
npx wrangler deploy

• La ruta debe cubrir todas las rutas del hostname, incluyendo /_redirhub/check.
• Las reglas comodín funcionan: cuando tu origen responde 404, el Worker redirige en su lugar.
• Los informes de 404 funcionan: los 404 de tu origen se informan cuando Report 404 pages está activado para el hostname.

Next.js (Vercel o autoalojado)#

Las redirecciones se ejecutan en tu proxy (Next.js 16) o middleware (Next.js 15 y anteriores), antes de tus páginas. Código fuente y opciones completas: redirhub/nextjs-redirects.

bashnpm install @redirhub/nextjs-redirects

Añade la dirección de las reglas y la clave como variables de entorno (configuración del proyecto en Vercel, o .env.local en local). Nunca antepongas NEXT_PUBLIC_ a la clave. Luego crea proxy.ts (o middleware.ts con export function middleware en Next.js 15 y 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
  // … tu propia lógica de proxy, o nada
}

• Llánalo primero, antes de las reescrituras y del manejo de locale.
• El matcher debe permitir /_redirhub/check y las rutas que quieres redirigir. Un matcher que omite cualquier ruta con un punto también omite reglas como /old.html.
• Las redirecciones en next.config se ejecutan antes del proxy, así que pueden ocultar tus reglas.
• El proxy se ejecuta antes de la página y nunca ve si tu aplicación responde 404, así que las reglas comodín y los informes 404 no se sirven allí. Para añadir ambas, usa createRedirects() y su afterSite(), donde sí ves la respuesta final, por ejemplo en un route handler (consulta el README).

Caddy#

Un módulo de Caddy v2 para tus propios servidores. Un solo Caddy puede servir todos tus dominios de integración desde una dirección de reglas del Workspace, y puede emitir certificados HTTPS bajo demanda solo para los nombres de host de tus reglas. Fuente y opciones completas: redirhub/caddy-redirects.

Compila Caddy con el módulo:

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

Para Caddy, copia la dirección de reglas del Workspace desde el panel de clave de integración en lugar de la dirección por dominio. Luego añade el manejador a tu 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
}

• Configura REDIRHUB_INTEGRATION_KEY en el entorno de Caddy y recarga Caddy.
• Los cambios llegan en uno o dos segundos mediante push, con el sondeo como respaldo. Las últimas reglas válidas se guardan en disco, así que un reinicio redirige al instante.
• Las reglas de comodín funcionan cuando el resto de la ruta responde 404. Detrás de try_files con un fallback (una aplicación de una sola página), el sitio nunca responde 404, así que el comodín nunca se activa.
• Los informes de 404 siguen el interruptor Reportar páginas 404 de cada nombre de host. Con report_404 all, se informa de cada 404 del bloque del sitio, incluso para nombres de host que no hayas añadido a RedirHub.

Después de desplegar#

• Abra el dominio en Hostnames y haga clic en Comprobar ahora. El estado debería cambiar a Conectado.
• Pruebe una regla en una ventana privada o con curl -I.
• Si el dominio permanece en Esperando o no se activa una redirección, consulte Solución de problemas del modo de integración.