Middleware Next.js : guide pratique — matcher, limites Edge Runtime et pièges courants

Les logs d’erreur Vercel. Le back-office venait d’être mis en ligne : en local, toutes les routes /dashboard étaient bien protégées — les visiteurs non connectés étaient redirigés vers la page de connexion. En production, un accès direct à /dashboard/settings/profile contournait la vérification et exposait des données sensibles.

J’ouvre le code : le fichier Middleware est bien là, la logique semble correcte. Alors, quoi ?

Après une demi-heure dans la doc Next.js, la réponse est dans la section matcher : j’avais écrit /dashboard/:path, qui ne couvre qu’un seul niveau comme /dashboard/settings. Les chemins multi-niveaux passaient à travers. La bonne forme : /dashboard/:path* — cet astérisque m’a évité de prendre la faute pour rien.

Ce n’est pas ma première mésaventure avec le Middleware. Bibliothèque incompatible Edge Runtime, matcher qui ne s’applique pas, boucle de redirection infinie… j’ai presque tout vu.

Si vous utilisez ou envisagez Next.js Middleware pour l’authentification, l’i18n ou les tests A/B, cet article devrait vous aider. Je détaille les pièges, les règles de configuration et trois cas complets.

Pas de formules creuses du type « à l’ère du développement web moderne ». Des problèmes concrets, comment écrire, comment éviter les pièges, et faire en sorte que le Middleware serve vraiment.

Qu’est-ce que le Middleware, et pourquoi l’utiliser ?

En bref, le Middleware est un poste de contrôle.

Avant qu’une requête n’atteigne votre page ou API, elle passe par ce filtre. Vous pouvez vérifier l’identité, modifier la requête, ou renvoyer une réponse directement — rediriger un visiteur non connecté, ou envoyer vers une version linguistique selon la région.

Il s’exécute sur Edge Runtime, point crucial. Edge Runtime ne tourne pas sur votre serveur, mais sur des nœuds edge proches de l’utilisateur (CDN). Faible latence, cold start quasi nul. Le Middleware est la couche de code la plus proche du visiteur.

Edge Runtime vs Node.js Runtime

En résumé : rapide, mais limité. Pas de modules Node.js (fs, path, etc.), ni la plupart des connexions base de données. C’est là que les pièges apparaissent le plus souvent.

Quand utiliser le Middleware ?

Toute logique ne convient pas au Middleware. Scénarios les plus courants :

1. Authentification (Auth Gate)
Le cas classique : vérifier si l’utilisateur est connecté, sinon rediriger vers /login. Plus rapide qu’une vérification dans un Server Component, car la requête n’atteint pas encore le serveur d’origine.

2. Internationalisation (i18n)
Selon la langue (URL, cookie ou navigateur), rediriger vers la bonne version : / → /zh ou /en.

3. Tests A/B
Répartir aléatoirement les utilisateurs entre deux versions de page. Un cookie maintient le groupe pour éviter un changement à chaque refresh.

4. Détection de bots et rate limiting
Bloquer les crawlers ou limiter la fréquence d’accès par IP.

5. Logs et analytics
Enregistrer chemin, referrer, user-agent et envoyer vers un service d’analyse.

6. Rewrite de contenu
Mapper en interne une URL vers un autre chemin sans changer la barre d’adresse. Utile pour routes dynamiques ou tests A/B.

Pourquoi ne pas faire tout ça dans les composants de page ?

C’est possible, mais plus lent. La logique des Server ou Client Components s’exécute après l’arrivée de la requête, voire après le rendu. Le Middleware intercepte à la edge : réponse plus rapide, meilleure UX.

Autre avantage : centralisation. Pas besoin de répéter l’authentification sur chaque page protégée — un seul endroit suffit.

Ne mettez pas pour autant toute la logique métier dans le Middleware. Requêtes BDD, calculs lourds : route API ou Server Component. Le Middleware doit rester léger et rapide.

Configuration de base et structure de fichiers

Où placer le fichier ?

Next.js impose une règle stricte : à la racine du projet ou dans src, nommé middleware.ts (ou .js).

racine-du-projet/
├── app/
├── middleware.ts    ← ici
├── package.json

Avec un dossier src :

racine-du-projet/
├── src/
│   ├── app/
│   ├── middleware.ts    ← ici
├── package.json

Attention : un seul fichier middleware.ts par projet. Pas de multiples middlewares dans app/ ou ailleurs — le Middleware est un gardien global.

Le Middleware minimal

import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  console.log('Requête entrante :', request.url);
  return NextResponse.next(); // laisser passer
}

NextResponse.next() signifie « OK, continuer » — la requête atteint la page ou l’API cible.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

API principales : NextRequest et NextResponse

NextRequest étend la Request Web standard :

• request.nextUrl : URL parsée (pathname, search, etc.)
• request.cookies : lecture/écriture des cookies
• request.geo : géolocalisation (selon la plateforme, ex. Vercel)

NextResponse offre plusieurs modes de retour :

1. Laisser passer

return NextResponse.next();

2. Redirection (URL visible change)

return NextResponse.redirect(new URL('/login', request.url));

3. Rewrite (redirection interne, URL inchangée)

return NextResponse.rewrite(new URL('/dashboard/v2', request.url));

L’utilisateur voit /dashboard mais reçoit le contenu de /dashboard/v2. Pratique pour tests A/B ou bascule de version.

4. Réponse directe

return new NextResponse('Accès refusé', { status: 403 });

Exemple : ajouter un header personnalisé

import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  response.headers.set('x-custom-header', 'my-value');
  return response;
}

Utile pour un timestamp ou marquer la source de la requête sur toutes les réponses.

Note de version (important)

Avec Next.js 15, middleware.ts a été renommé en proxy.ts. middleware.ts reste compatible ; les nouveaux projets peuvent adopter le nouveau nom. Ce guide couvre Next.js 14/15 — concepts et API identiques.

Correspondance de chemins (Matcher) : la zone la plus piégeuse

Le matcher, c’est là que j’ai le plus trébuché.

Pourquoi un matcher ?

Sans matcher, le Middleware s’exécute sur chaque requête — CSS, JS, images, polices. Une page peut déclencher 20 exécutions pour 20 assets statiques : gaspillage et ralentissement.

Le matcher indique à Next.js : « n’exécuter le Middleware que sur ces chemins ».

Syntaxe de base

Exporter un objet config dans middleware.ts :

export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*']
}

Seuls les chemins commençant par /dashboard et /api déclenchent le Middleware.

Modificateurs : *, +, ?

* (zéro ou plus)
/dashboard/:path* correspond à :

• /dashboard ✓
• /dashboard/settings ✓
• /dashboard/settings/profile ✓

+ (un ou plus)
/dashboard/:path+ :

• /dashboard ✗
• /dashboard/settings ✓
• /dashboard/settings/profile ✓

? (zéro ou un)
/dashboard/:path? :

• /dashboard ✓
• /dashboard/settings ✓
• /dashboard/settings/profile ✗

Dans la plupart des cas, * suffit.

Pièges courants et solutions (essentiel)

Piège classique : les assets statiques

export const config = {
  matcher: ['/:path*'] // vouloir tout matcher
}

Résultat : _next/static est aussi intercepté, le Middleware s’exécute en boucle, la page devient très lente.

Solution : lookahead négatif

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
}

« Matcher tout sauf api, _next/static, _next/image et favicon.ico. »

La regex est tordue — reprenez l’exemple officiel tel quel.

Pas de valeurs dynamiques dans matcher

const lang = 'zh';
export const config = {
  matcher: [`/${lang}/:path*`] // ❌ interdit
}

Le matcher doit être statique, connu à la compilation. Pas de template avec variables, pas de génération à l’exécution.

Pour une logique dynamique, placez-la dans la fonction middleware :

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  if (pathname.startsWith('/zh') || pathname.startsWith('/en')) {
    // traitement
  }
  return NextResponse.next();
}

export const config = {
  matcher: ['/:locale/:path*']
}

Modèles matcher recommandés

Protéger des routes spécifiques (back-office) :

export const config = {
  matcher: ['/dashboard/:path*', '/admin/:path*']
}

Tout matcher sauf les assets statiques :

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|.*\\.png$).*)',
  ],
}

Protéger toutes les routes API :

export const config = {
  matcher: ['/api/:path*']
}

La doc Next.js sur le matcher reste succincte — ce tableau résume des heures de galère. Espérons qu’il vous fera gagner du temps.

Limites Edge Runtime et contournements

La première fois, j’étais perdu. Je voulais valider un utilisateur en interrogeant la base depuis le Middleware. En local : Native Node.js APIs are not supported in the Edge Runtime.

Connecter une BDD, c’est interdit ?

Edge Runtime n’est pas un environnement Node.js complet — beaucoup d’API et de bibliothèques courantes sont indisponibles.

Ce qu’Edge Runtime ne supporte pas

Impact concret

1. Pas de connexion BDD directe pour l’authentification
2. Pas de lecture de fichier config (ex. config.json)
3. Pas de bibliothèques tierces dépendant de Node.js

Des contournements existent pourtant.

Stratégie : Edge Runtime comme avant-poste

Le Middleware ne fait qu’un jugement léger ; la logique lourde passe à l’étape suivante.

Exemple : validation JWT (recommandé)

Le JWT est sans état — le token contient les infos, pas besoin de BDD.

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

import { NextRequest, NextResponse } from 'next/server';
import { jwtVerify } from 'jose'; // compatible Edge Runtime

export async function middleware(request: NextRequest) {
  const token = request.cookies.get('auth-token')?.value;

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    const secret = new TextEncoder().encode(process.env.JWT_SECRET);
    const { payload } = await jwtVerify(token, secret);

    const response = NextResponse.next();
    response.headers.set('x-user-id', payload.userId as string);
    return response;
  } catch (error) {
    const response = NextResponse.redirect(new URL('/login', request.url));
    response.cookies.delete('auth-token');
    return response;
  }
}

export const config = {
  matcher: ['/dashboard/:path*']
}

Points clés :

• jose plutôt que jsonwebtoken (dépend de crypto Node.js)
• Secret JWT via process.env (disponible sur Edge)
• En cas d’échec, supprimer le cookie

Si la BDD est obligatoire

Ex. vérifier si un compte est suspendu — appeler une route API depuis le Middleware :

export async function middleware(request: NextRequest) {
  const userId = request.cookies.get('user-id')?.value;

  if (!userId) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  const apiUrl = new URL('/api/check-user-status', request.url);
  const response = await fetch(apiUrl, {
    headers: { 'x-user-id': userId }
  });

  const { isActive } = await response.json();

  if (!isActive) {
    return NextResponse.redirect(new URL('/account-suspended', request.url));
  }

  return NextResponse.next();
}

La route API tourne en Node.js et peut accéder à la BDD — au prix d’une latence supplémentaire.

Web Crypto API

Pour chiffrement/hachage, API native du navigateur :

const data = new TextEncoder().encode('hello world');
const hashBuffer = await crypto.subtle.digest('SHA-256', data);
const hashArray = Array.from(new Uint8Array(hashBuffer));
const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');

Plus verbeux que crypto Node.js, mais seule option sur Edge.

Comment savoir si une bibliothèque supporte Edge ?

Lire la doc ou tester. Message Native Node.js APIs are not supported = incompatible.

Alternatives courantes :

• JWT : jose au lieu de jsonwebtoken
• BDD : Vercel Postgres, Supabase, Prisma (partiel)
• Logs : Logtail, Axiom

Conseil : ne pas surcharger le Middleware. Rapide entrée/sortie ; le lourd reste dans les routes API.

Cas pratiques : trois scénarios complets

Assez de théorie — voici trois cas réels, prêts à copier.

Cas 1 : Authentification et protection de routes

Scénario : back-office où tout /dashboard/* exige une connexion.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { jwtVerify } from 'jose';

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const token = request.cookies.get('auth-token')?.value;

  if (!token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('from', pathname);
    return NextResponse.redirect(loginUrl);
  }

  try {
    const secret = new TextEncoder().encode(process.env.JWT_SECRET);
    const { payload } = await jwtVerify(token, secret);

    const expiresAt = payload.exp as number;
    const now = Math.floor(Date.now() / 1000);
    const shouldRefresh = expiresAt - now < 3600;

    const response = NextResponse.next();

    if (shouldRefresh) {
      response.headers.set('x-token-refresh-needed', 'true');
    }

    response.headers.set('x-user-id', payload.userId as string);
    response.headers.set('x-user-role', payload.role as string);

    return response;
  } catch (error) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('from', pathname);
    loginUrl.searchParams.set('reason', 'expired');

    const response = NextResponse.redirect(loginUrl);
    response.cookies.delete('auth-token');
    return response;
  }
}

export const config = {
  matcher: ['/dashboard/:path*']
}

Points clés :

1. Paramètre from pour revenir après connexion
2. Renouvellement anticipé si expiration proche
3. Infos utilisateur dans les headers (optionnel)

Tests :

• Sans cookie, /dashboard → /login?from=/dashboard
• Avec cookie valide → affichage normal

Problème fréquent : OK en local, KO en prod — JWT_SECRET manquant sur Vercel/Netlify.

Cas 2 : Redirection i18n

Scénario : site bilingue ; / redirige vers /zh ou /en selon la préférence.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

const supportedLocales = ['en', 'zh', 'ja'];
const defaultLocale = 'en';

function getPreferredLocale(request: NextRequest): string {
  const urlLocale = request.nextUrl.searchParams.get('lang');
  if (urlLocale && supportedLocales.includes(urlLocale)) {
    return urlLocale;
  }

  const cookieLocale = request.cookies.get('NEXT_LOCALE')?.value;
  if (cookieLocale && supportedLocales.includes(cookieLocale)) {
    return cookieLocale;
  }

  const acceptLanguage = request.headers.get('accept-language');
  if (acceptLanguage) {
    const browserLang = acceptLanguage.split(',')[0].split('-')[0];
    if (supportedLocales.includes(browserLang)) {
      return browserLang;
    }
  }

  return defaultLocale;
}

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  const pathnameHasLocale = supportedLocales.some(
    locale => pathname.startsWith(`/${locale}/`) || pathname === `/${locale}`
  );

  if (!pathnameHasLocale) {
    const locale = getPreferredLocale(request);
    const newUrl = new URL(`/${locale}${pathname}`, request.url);
    newUrl.search = request.nextUrl.search;

    const response = NextResponse.redirect(newUrl);
    response.cookies.set('NEXT_LOCALE', locale, {
      maxAge: 60 * 60 * 24 * 30,
      path: '/'
    });

    return response;
  }

  return NextResponse.next();
}

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|.*\\.).*)'
  ]
}

Points clés :

1. Priorité : param URL > cookie > navigateur
2. Cookie pour mémoriser le choix
3. Matcher exclut les assets statiques

Avec next-intl :

import { createI18nMiddleware } from 'next-intl/middleware';

export default createI18nMiddleware({
  locales: ['en', 'zh', 'ja'],
  defaultLocale: 'en'
});

export const config = {
  matcher: ['/((?!api|_next|.*\\.).)']
};

next-intl gère détection, cookies, etc.

Cas 3 : Tests A/B et feature flags

Scénario : nouvelle page d’accueil pour 50 % des visiteurs.

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  if (pathname !== '/') {
    return NextResponse.next();
  }

  let variant = request.cookies.get('ab-test-homepage')?.value;

  if (!variant) {
    variant = Math.random() < 0.5 ? 'A' : 'B';
  }

  let response: NextResponse;

  if (variant === 'B') {
    response = NextResponse.rewrite(new URL('/homepage-v2', request.url));
  } else {
    response = NextResponse.next();
  }

  response.cookies.set('ab-test-homepage', variant, {
    maxAge: 60 * 60 * 24 * 7,
    path: '/'
  });

  response.headers.set('x-ab-variant', variant);
  return response;
}

export const config = {
  matcher: ['/']
}

Points clés :

1. rewrite plutôt que redirect — URL reste /
2. Cookie pour un groupe stable
3. Header x-ab-variant pour l’analytics

Tracking dans la page :

// app/page.tsx
import { headers } from 'next/headers';

export default function HomePage() {
  const headersList = headers();
  const abVariant = headersList.get('x-ab-variant');

  useEffect(() => {
    analytics.track('page_view', {
      page: 'homepage',
      variant: abVariant
    });
  }, [abVariant]);

  return <div>...</div>;
}

Groupement par user ID (stable multi-appareils) :

const userId = request.cookies.get('user-id')?.value;

if (userId) {
  const hash = simpleHash(userId);
  variant = hash % 2 === 0 ? 'A' : 'B';
} else {
  variant = request.cookies.get('ab-test-homepage')?.value ||
            (Math.random() < 0.5 ? 'A' : 'B');
}

function simpleHash(str: string): number {
  let hash = 0;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) - hash) + str.charCodeAt(i);
    hash |= 0;
  }
  return Math.abs(hash);
}

Ces trois cas couvrent l’essentiel. Combinez-les : auth + i18n sur le même Middleware.

Optimisation des performances et bonnes pratiques

Écrire un Middleware est facile ; le bien écrire demande de l’expérience.

Organisation modulaire

Un seul middleware.ts autorisé, mais la logique peut être découpée :

racine-du-projet/
├── middleware/
│   ├── auth.ts
│   ├── i18n.ts
│   ├── ab-test.ts
│   └── rate-limit.ts
├── middleware.ts

Point d’entrée :

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { checkAuth } from './middleware/auth';
import { handleI18n } from './middleware/i18n';
import { handleABTest } from './middleware/ab-test';

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  const i18nResponse = handleI18n(request);
  if (i18nResponse) return i18nResponse;

  if (pathname.startsWith('/dashboard')) {
    const authResponse = await checkAuth(request);
    if (authResponse) return authResponse;
  }

  if (pathname === '/') {
    return handleABTest(request);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)']
}

auth.ts :

// middleware/auth.ts
import { NextRequest, NextResponse } from 'next/server';
import { jwtVerify } from 'jose';

export async function checkAuth(request: NextRequest): Promise<NextResponse | null> {
  const token = request.cookies.get('auth-token')?.value;

  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  try {
    const secret = new TextEncoder().encode(process.env.JWT_SECRET);
    await jwtVerify(token, secret);
    return null;
  } catch {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}

Cache : réduire les calculs répétés

Vercel Edge Config pour des feature flags :

import { get } from '@vercel/edge-config';

export async function middleware(request: NextRequest) {
  const featureFlags = await get('feature-flags');

  if (featureFlags?.newDashboard) {
    return NextResponse.rewrite(new URL('/dashboard-v2', request.url));
  }

  return NextResponse.next();
}

Edge Config : stockage clé-valeur distribué, lecture très rapide.

Éviter des headers trop volumineux

Headers trop grands → erreur 431 Request Header Fields Too Large.

Recommandations :

• Total headers < 8 Ko
• Infos essentielles uniquement
• Données volumineuses : token chiffré

// ❌ éviter
response.headers.set('x-user-data', JSON.stringify(userData));

// ✅ préférer
response.headers.set('x-user-id', user.id);
response.headers.set('x-user-role', user.role);

Matcher : précision > wildcard

// moins bon
export const config = {
  matcher: ['/:path*']
}

// mieux
export const config = {
  matcher: ['/dashboard/:path*', '/api/:path*']
}

Monitoring et débogage

En développement :

export function middleware(request: NextRequest) {
  if (process.env.NODE_ENV === 'development') {
    console.log('Middleware :', {
      path: request.nextUrl.pathname,
      method: request.method,
      cookies: request.cookies.getAll()
    });
  }
  // ...
}

En production : logs vers un service tiers

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

import { Logger } from '@logtail/edge';

const logger = new Logger(process.env.LOGTAIL_TOKEN);

export async function middleware(request: NextRequest) {
  try {
    // ...
  } catch (error) {
    await logger.error('Middleware error', {
      path: request.nextUrl.pathname,
      error: error.message
    });
    throw error;
  }
}

Checklist

✅ À faire :

• Middleware léger ; logique lourde en route API
• Matcher précis
• JWT pour l’auth
• Code modulaire par fonction
• Logs de debug en dev
• Cookies avec expiration raisonnable

❌ À éviter :

• Calculs lourds ou requêtes BDD dans le Middleware
• Oublier le matcher
• Bibliothèques dépendant de Node.js
• Headers > 8 Ko
• Logs massifs en production
• Boucles de redirection infinies

Erreurs courantes et débogage

Erreur 1 : le Middleware ne s’exécute pas

export function middleware(request: NextRequest) {
  console.log('🔥 Middleware exécuté ! Chemin :', request.nextUrl.pathname);
  // ...
}

Si ce log n’apparaît pas, le Middleware ne tourne pas.

Erreur 2 : Native Node.js APIs are not supported in the Edge Runtime

Coupables fréquents : fs, path, jsonwebtoken, drivers MongoDB/MySQL.

1. Trouver une alternative Edge
2. Déplacer vers une route API
3. Web Crypto API à la place de crypto Node.js

// ❌
import jwt from 'jsonwebtoken';

// ✅
import { jwtVerify } from 'jose';

Erreur 3 : Invalid middleware found

Matcher vide :

export const config = { matcher: [] } // ❌

Export manquant :

export function middleware(request: NextRequest) { ... } // ✅

Pas de return :

export function middleware(request: NextRequest) {
  return NextResponse.next(); // obligatoire
}

Erreur 4 : boucle de redirection infinie

ERR_TOO_MANY_REDIRECTS — la cible de redirection est aussi interceptée.

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  if (pathname === '/login' || pathname === '/') {
    return NextResponse.next();
  }

  const token = request.cookies.get('auth-token');
  if (!token) {
    return NextResponse.redirect(new URL('/login', request.url));
  }

  return NextResponse.next();
}

Ou matcher ciblé : matcher: ['/dashboard/:path*']

Erreur 5 : variables d’environnement undefined

1. .env.local absent ou nom incorrect
2. Variables non configurées sur Vercel/Netlify
3. Nom non conforme aux règles Next.js

// .env.local
JWT_SECRET=your-secret-here

Redémarrer le serveur dev après modification ; côté client, préfixe NEXT_PUBLIC_.

Astuces de débogage

Headers de traçage :

export function middleware(request: NextRequest) {
  const response = NextResponse.next();
  response.headers.set('x-middleware-executed', 'true');
  response.headers.set('x-middleware-path', request.nextUrl.pathname);
  return response;
}

Commenter par étapes pour localiser l’erreur.

Logs Vercel Edge Functions dans l’onglet Functions du projet.

Turbo en local (Next.js 15+) :

npm run dev -- --turbo

Conclusion

Trois idées à retenir :

1. Connaître les limites du Middleware

Auth légère, redirections, tests A/B : oui. Logique métier lourde, BDD, calculs : route API ou Server Component. Le Middleware est un gardien rapide, pas un majordome.

2. Le matcher est primordial

Routes dynamiques : *. Assets statiques : exclus. Pages publiques (/login) : non interceptées. En doute, reprenez les modèles ci-dessus ou loggez les chemins en dev.

3. Accepter les limites Edge Runtime

Ce n’est pas Node.js complet — vitesse et distribution mondiale en échange. JWT, Web Crypto API, appels API : les bons outils pour contourner.

Next.js Middleware n’est pas complexe, mais riche en détails. Matcher, Edge Runtime, redirections infinies — je les ai vus. Cet article vise à vous faire gagner du temps.

Pour une interception globale, testez le Middleware, puis optimisez. En cas de blocage, revenez à la section débogage.

Si cet article vous a aidé, partagez-le avec vos collègues Next.js. Prochain sujet de ma part : Server Actions — là aussi, les pièges ne manquent pas.

Bon courage — que votre Middleware fonctionne du premier coup.