Configurer le mode d'intégration sur Cloudflare Workers, Next.js ou Caddy

Cette page explique comment connecter un domaine en Integration Mode sur les trois plateformes qui disposent d’une intégration open source prête à l’emploi. Chacune sert les redirections, les liens courts et les liens de codes QR que vous gérez dans RedirHub à partir d’un fichier de règles, sans redéploiement pour chaque modification, et renvoie chaque redirection vers vos analyses.

Avant de commencer : l’adresse des règles et la clé#

1. Dans le tableau de bord, ajoutez le domaine sous Hostnames et choisissez Connect through your own platform.
2. Choisissez votre plateforme. Le tableau de bord affiche l’adresse des règles pour le domaine et la clé d’intégration de votre espace de travail, ainsi qu’une invite avec les deux préremplis que vous pouvez coller dans un agent de codage IA (Claude, Cursor, ChatGPT et autres) au lieu de suivre les étapes ci-dessous manuellement.
3. Stockez la clé comme secret ou variable d’environnement. L’adresse des règles n’est pas un secret, mais ne la publiez pas.

Après le déploiement, la première réponse sur /_redirhub/check connecte le domaine. Le tableau de bord vérifie toutes les 15 minutes, ou immédiatement avec Check now.

Cloudflare Workers#

Un Worker placé devant votre origine sert les redirections et transmet toutes les autres requêtes. Source et options complètes : redirhub/cloudflare-redirects.

bashnpm install @redirhub/cloudflare-redirects

Créez 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 }),
})

Définissez une route pour le nom d’hôte et l’adresse des règles dans wrangler.toml (le tableau de bord affiche les noms de variables exacts pour votre domaine) :

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"

Ajoutez la clé comme secret et déployez :

bashnpx wrangler secret put ACME_INTEGRATION_KEY
npx wrangler deploy

• La route doit couvrir chaque chemin du nom d’hôte, y compris /_redirhub/check.
• Les règles de type fourre-tout fonctionnent : lorsque votre origine renvoie 404, le Worker effectue une redirection à la place.
• Les rapports 404 fonctionnent : les 404 de votre origine sont signalés lorsque Signaler les pages 404 est activé pour le nom d’hôte.

Next.js (Vercel ou auto-hébergé)#

Les redirections s’exécutent dans votre proxy (Next.js 16) ou votre middleware (Next.js 15 et versions antérieures), avant vos pages. Source et options complètes : redirhub/nextjs-redirects.

bashnpm install @redirhub/nextjs-redirects

Ajoutez l’adresse des règles et la clé en tant que variables d’environnement (paramètres du projet Vercel, ou .env.local en local). Ne préfixez jamais la clé avec NEXT_PUBLIC_. Créez ensuite proxy.ts (ou middleware.ts avec export function middleware sur Next.js 15 et versions antérieures) :

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
  // … votre propre logique de proxy, ou rien
}

• Appelez-le en premier, avant les réécritures et la gestion des langues.
• Le matcher doit laisser passer /_redirhub/check et les chemins que vous redirigez. Un matcher qui ignore tous les chemins contenant un point ignore aussi des règles comme /old.html.
• Les redirections dans next.config s’exécutent avant le proxy, elles peuvent donc éclipser vos règles.
• Le proxy s’exécute avant la page et ne voit jamais si votre application renvoie une 404, donc les règles génériques et les rapports 404 n’y sont pas servis. Pour ajouter les deux, utilisez createRedirects() et son afterSite(), où vous voyez la réponse finale, par exemple dans un gestionnaire de route (voir le README).

Caddy#

Un module Caddy v2 pour vos propres serveurs. Un seul Caddy peut servir tous vos domaines d’intégration à partir d’une seule adresse des règles du Workspace, et il peut émettre des certificats HTTPS à la demande uniquement pour les noms d’hôte présents dans vos règles. Source et options complètes : redirhub/caddy-redirects.

Construisez Caddy avec le module :

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

Pour Caddy, copiez l’adresse des règles du Workspace depuis le panneau de la clé d’intégration au lieu de l’adresse par domaine. Ajoutez ensuite le gestionnaire à votre 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
}

• Définissez REDIRHUB_INTEGRATION_KEY dans l’environnement de Caddy et rechargez Caddy.
• Les changements arrivent en une seconde ou deux par push, avec le polling en solution de secours. Les dernières bonnes règles sont conservées sur le disque, donc un redémarrage déclenche immédiatement les redirections.
• Les règles génériques fonctionnent lorsque le reste de la route répond 404. Derrière try_files avec un fallback (une application monopage), le site ne répond jamais 404, donc la règle générique ne s’exécute jamais.
• Les rapports 404 suivent le commutateur Rapporter les pages 404 de chaque nom d’hôte. Avec report_404 all, chaque 404 du bloc du site est signalé, même pour les noms d’hôte que vous n’avez pas ajoutés à RedirHub.

Après votre déploiement#

• Ouvrez le domaine sous Hostnames et cliquez sur Vérifier maintenant. L'état devrait passer à Connecté.
• Testez une règle dans une fenêtre privée ou avec curl -I.
• Si le domaine reste sur En attente ou qu'une redirection ne se déclenche pas, consultez Dépannage du mode d'intégration.