Middleware Vercel
Vercel est une plateforme cloud qui permet de déployer des applications JavaScript dans le cloud. C'est une excellente plateforme pour déployer des fonctions sans serveur ou des applications full-stack. Cette page explique comment intégrer redirection.io à une application Vercel.
Pour installer redirection.io dans votre application hébergée sur Vercel, il existe principalement deux options :
- en utilisant les instances managées de redirection.io, qui sont hébergées par redirection.io et ne nécessitent aucune configuration spécifique de votre part. C'est le moyen le plus simple d'utiliser redirection.io, mais veuillez noter que Vercel ne recommande pas spécifiquement l'utilisation d'un proxy inverse devant leur plateforme, sauf si vous utilisez le plan Enterprise, qui permet des configurations réseau personnalisées.
- en utilisant le middleware Vercel de redirection.io. Dans cette configuration, redirection.io sera exécuté en tant que middleware dans votre application Vercel, et pourra intercepter et analyser les requêtes et les réponses. En raison des restrictions de Vercel sur les proxys inverses tiers, c'est le moyen recommandé d'utiliser redirection.io avec Vercel.
Prérequis
Avant de commencer l'intégration de redirection.io avec votre application Vercel, vous devez avoir :
- la capacité d'installer un package dans votre application Vercel ;
- la capacité de déployer une application Vercel et de configurer des variables d'environnement.
Utilisation du middleware Vercel de redirection.io
Le déploiement de redirection.io sur Vercel nécessite plusieurs étapes :
- créer un compte redirection.io ;
- créer une organisation et un projet redirection.io. À cette étape, vous voudrez peut-être inviter vos collaborateurs ;
- Installer le middleware Vercel de redirection.io dans votre application Vercel ;
- Configurer le middleware Vercel de redirection.io avec votre clé de projet en utilisant une variable d'environnement Vercel ;
- Déployer votre application Vercel.
Installer le middleware Vercel de redirection.io
Dans votre application Vercel, installez le package @redirection.io/vercel-middleware
:
npm install @redirection.io/vercel-middleware
// or with yarn
yarn add @redirection.io/vercel-middleware
Ce package est disponible en tant que package open source sur npm et sur notre page GitHub.
Utiliser le middleware redirection.io dans votre application
Une fois installé, le middleware doit être utilisé par votre application Vercel. L'approche dépend de si votre application utilise déjà un middleware ou non.
Mon application n'a pas de middleware
Si aucun middleware n'est actuellement utilisé par votre application, nous devrons en créer un ! Pour ce faire, créez un nouveau fichier nommé middleware.ts
à la racine de votre application Vercel (au même niveau que les dossiers app
ou pages
, éventuellement dans un dossier src
si votre projet en utilise un), et ajoutez le code suivant :
import redirectionioMiddleware from '@redirection.io/vercel-middleware/next';
export default redirectionioMiddleware;
export const config = {
unstable_allowDynamic: [
'/node_modules/@redirection.io/**',
],
}
Par défaut, notre middleware ignore certaines routes même s'il existe une configuration exportée. Les routes ignorées sont :
- les routes
/api/*
/next/*
(internes à Next.js)/static/*
(à l'intérieur de/public
)- tous les fichiers racines à l'intérieur de
/public
(par exemple/favicon.ico
)
Si vous souhaitez personnaliser les routes que le middleware gère, utilisez la fonction createRedirectionIoMiddleware()
et fournissez votre propre regex à l'aide de l'option matcherRegex
:
import { createRedirectionIoMiddleware } from "@redirection.io/vercel-middleware/next";
const middleware = createRedirectionIoMiddleware({
matcherRegex: "^/((?!api).*)$" // Votre regex ici
});
export default middleware;
export const config = {
unstable_allowDynamic: [
'/node_modules/@redirection.io/**',
],
}
Si vous souhaitez que le middleware gère toutes les routes sans aucune exclusion, vous pouvez définir l'option matcherRegex
à null
:
createRedirectionIoMiddleware({ matcherRegex: null });
Mon application utilise déjà un middleware Vercel
Si votre application contient déjà un middleware Vercel, le mode d'intégration décrit ci-dessus ne vous conviendra pas. Au lieu de cela, vous devrez modifier le middleware existant afin que le middleware redirection.io l'enveloppe.
Supposons que votre middleware actuel ressemble à ceci :
export default async function middleware(req: NextRequest) {
// here
// your
// middleware
// code
}
export const config = {
matcher: ['/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)'],
};
Déplacez votre code dans une fonction dédiée :
const myMiddleware = async (req: NextRequest) => {
// ici
// votre
// code
// middleware
};
export const config = {
matcher: ['/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)'],
};
Et utilisez createRedirectionIoMiddleware
depuis @redirection.io/vercel-middleware/next
pour envelopper votre code de middleware dans le middleware redirection.io, grâce aux options previousMiddleware
ou nextMiddleware
.
Si vous utilisez previousMiddleware
, le code de votre middleware sera exécuté avant que redirection.io n'exécute sa logique. Si vous choisissez nextMiddleware
, il sera exécuté après que redirection.io ait été exécuté (et, potentiellement, il pourrait ne pas être exécuté du tout si une redirection doit être effectuée) :
import { createRedirectionIoMiddleware } from "@redirection.io/vercel-middleware/next";
const myMiddleware = async (req: NextRequest) => {
// ici
// votre
// code
// middleware
};
const middleware = createRedirectionIoMiddleware({
previousMiddleware: myMiddleware, // Dans ce cas, votre middleware est exécuté avant le middleware redirection.io
nextMiddleware: myMiddleware, // Dans ce cas, votre middleware est exécuté après le middleware redirection.io
});
export default middleware;
export const config = {
unstable_allowDynamic: ["/node_modules/@redirection.io/**"],
};
Si la configuration de votre middleware contient l'option "matcher" (pour restreindre les requêtes qui doivent passer par le middleware), celle-ci sera utilisée en amont de notre middleware.
Si la regex est validée, notre middleware utilisera alors une deuxième regex par défaut (qui ignore les éléments internes de Next.js et les fichiers statiques) :
^/((?!api|static|.*\\..*|_next|favicon.ico|robots.txt).*)$
Vous pouvez modifier cette regex par défaut en utilisant l'option matcherRegex
de la fonction createRedirectionIoMiddleware
:
const middleware = createRedirectionIoMiddleware({
matcherRegex: "^/((?!api/auth).*)$", // Votre regex ici
});
Veuillez noter que l'expression régulière est un peu différente de celle qui se trouvait dans l'option matcher
: elle commence maintenant par un ^
et se termine par un $
Si votre projet n'est pas basé sur Next.js, tout le code ci-dessus peut être adapté pour importer depuis @redirection.io/vercel-middleware
au lieu de @redirection.io/vercel-middleware/next
.
Configurer le middleware Vercel de redirection.io
Dans les paramètres de votre application Vercel, ajoutez une nouvelle variable d'environnement nommée REDIRECTIONIO_TOKEN
avec la valeur de votre clé de projet redirection.io :
Déployer votre application Vercel
Une fois le middleware Vercel de redirection.io installé et configuré, vous pouvez déployer votre application Vercel. Le middleware Vercel de redirection.io sera exécuté à chaque requête, il analysera les requêtes et les réponses et permettra des modifications de réponse faciles.
Variables d'environnement prises en charge
Le comportement du middleware Vercel de redirection.io peut être personnalisé à l'aide de plusieurs variables d'environnement à créer dans les paramètres du projet Vercel :
REDIRECTIONIO_TOKEN
- Cette directive est requise
- Description : il s'agit de la "clé de projet" du projet redirection.io auquel le trafic de ce site doit être associé
REDIRECTIONIO_ADD_HEADER_RULE_IDS
- Cette directive est optionnelle
- Par défaut : false
- Description : définissez cette valeur sur
true
pour ajouter un en-tête de réponseX-RedirectionIo-RuleIds
contenant l'identifiant des règles redirection.io exécutées, séparés par un;
REDIRECTIONIO_INSTANCE_NAME
- Cette directive est optionnelle
- Par défaut :
redirection-io-vercel-middleware
- Description : c'est le nom de cette instance de middleware Vercel, tel qu'il doit être affiché dans l'écran "instances" du gestionnaire redirection.io
REDIRECTIONIO_TIMEOUT
- Cette directive est optionnelle
- Par défaut :
500
- Description : définit le délai d'expiration maximal pour les appels d'API redirection.io (en ms). Si ce délai d'expiration est atteint, aucune règle n'est appliquée à la requête.
Dépannage
Avec quelle version de Next.js ce middleware est-il compatible ?
Le middleware Vercel de redirection.io est compatible avec Next.js 14.2 au minimum.
Avez-vous des exemples d'intégration de redirection.io avec Next.js ?
Nous proposons un dépôt qui inclut plusieurs exemples d'intégration de Next.js avec Redirection.io :
- Intégration Storyblok : une démo montrant comment intégrer redirection.io à une application Next.js utilisant Storyblok CMS.
- Intégration Auth0 : un exemple de configuration de Next.js avec l'authentification Auth0 et redirection.io.
- Intégration Next-intl : un guide montrant comment utiliser Next.js avec next-intl pour l'internationalisation, combiné avec redirection.io.
Chaque exemple est accompagné d'instructions de configuration détaillées dans ses sous-répertoires respectifs au sein du dépôt d'exemples.
Pourquoi utilisez-vous unstable_allowDynamic
dans la configuration du middleware ?
La documentation de Next.js explique que certaines fonctionnalités sont désactivées dans l'environnement d'exécution Next.js Edge, en particulier l'exécution de code dynamique.
La directive de configuration unstable_allowDynamic
est un moyen d'assouplir l'analyse statique du code et peut être utilisée pour permettre le chargement de fichiers spécifiques dans un middleware même si une partie d'entre eux contient des fonctionnalités non prises en charge. Ceci est particulièrement utile si vous dépendez d'une fonctionnalité offerte par une bibliothèque qui regroupe de telles déclarations non prises en charge.
Le middleware redirection.io s'appuie sur la bibliothèque getrandom pour générer des données aléatoires lors de l'utilisation d'un trigger "sampling". Malheureusement, des parties de cette bibliothèque, qui ne seront jamais exécutées par le middleware redirection.io, peuvent entraîner l'exécution de code dynamique dans des conditions très spécifiques (sur node.js, lorsqu'un module spécifique n'est pas disponible) qui ne peuvent pas être remplies lors de l'utilisation du middleware.
C'est la seule raison pour laquelle unstable_allowDynamic
est nécessaire pour exécuter le middleware redirection.io.
Dois-je modifier des choses si j'utilise pnpm au lieu de npm ou yarn ?
Si vous utilisez pnpm, l'emplacement d'installation du module n'est pas dans /node_modules
mais dans un dossier .pnpm
. Dans ce cas, vous pouvez utiliser ["/node_modules/.pnpm/**/@redirection.io/**"]
comme valeur de configuration pour unstable_allowDynamic
.
En d'autres termes, dans ce cas, vous configurerez votre middleware de base comme ceci :
import redirectionioMiddleware from '@redirection.io/vercel-middleware/next';
export default redirectionioMiddleware;
export const config = {
unstable_allowDynamic: [
'/node_modules/.pnpm/**/@redirection.io/**',
],
}