Middleware in Next.js: Authentifizierung, Logging und Feature Flags

Stell dir vor, du betreibst eine Webanwendung mit geschützten Bereichen, dynamischen Features und verschiedenen Benutzergruppen. Wie kannst du sicherstellen, dass ein Nutzer nur auf Inhalte zugreift, für die er berechtigt ist? Oder wie erfährst du, welche Routen besonders oft aufgerufen werden? Und wie aktivierst du bestimmte Funktionen nur für ausgewählte Nutzer, ohne deine gesamte App umzustrukturieren?

Die Antwort auf diese Fragen liegt in der Middleware von Next.js. Mit der Middleware kannst du Code ausführen, bevor eine Anfrage abgeschlossen wird. Das erlaubt dir, Anfragen zu analysieren, Weiterleitungen zu erstellen oder sogar Feature-Flags einzusetzen – und das alles, bevor deine App eine Seite rendert.

In diesem Artikel zeige ich dir, wie du Middleware gezielt im App Router von Next.js einsetzt. Du lernst die Grundlagen, typische Einsatzszenarien wie Authentifizierung, Logging und Feature Flags sowie Best Practices kennen. Mit praxisnahen Beispielen wirst du schnell erkennen, wie mächtig und flexibel Middleware ist, um deine Webanwendung effizienter zu gestalten.

Grundlagen der Middleware

Die Middleware in Next.js ist ein leistungsstarkes Werkzeug, um Code direkt im Anfrage-Lebenszyklus auszuführen – und zwar bevor die eigentliche Seite oder API-Route aufgerufen wird. Sie ermöglicht dir, Anfragen zu analysieren, umzuleiten oder zu modifizieren, ohne zusätzliche Server-Logik oder komplexe Client-Skripte.

Was ist Middleware in Next.js?

Middleware agiert wie ein "Türsteher" für eingehende Anfragen. Bevor die Anfrage die eigentliche Route erreicht, kannst du mit Middleware:

• Weiterleitungen und Umleitungen durchführen.
• Anfragen analysieren und Metadaten wie Cookies oder Header auslesen.
• Antworten manipulieren, z. B. durch das Hinzufügen von Headern oder das Setzen von Cookies.
• Dynamische Routenumschreibungen (Rewrites) erstellen, z. B. für A/B-Tests oder Feature-Rollouts.

Unterschied zwischen Middleware und Route Handlers

Es gibt eine wichtige Unterscheidung: Middleware läuft vor der Routenverarbeitung, während Route Handlers (z. B. API- oder Page-Dateien) die tatsächliche Verarbeitung und Ausgabe übernehmen.

Middleware ist ideal, wenn du Aktionen ausführen möchtest, die leichtgewichtig und performant sind – z. B. die Prüfung von Cookies oder die Protokollierung von Anfragen.

Wie und wo wird Middleware eingebunden?

In Next.js wird Middleware in einer speziellen Datei namens middleware.ts (oder .js) definiert. Diese Datei liegt im Root-Verzeichnis deines Projekts, typischerweise auf der gleichen Ebene wie app. Falls du ein src-Verzeichnis verwendest, gehört die Middleware-Datei dort hinein.

Ein einfaches Beispiel mit if-Bedingungen:

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

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/admin')) {
    const token = request.cookies.get('auth-token');
    if (!token) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }

  if (request.nextUrl.pathname.startsWith('/api')) {
    console.log(`API-Anfrage: ${request.url}`);
  }

  return NextResponse.next();
}

Durch die Verwendung von if-Bedingungen kannst du je nach Route oder Anfrage unterschiedliche Logik ausführen. Das macht die Middleware langfristig flexibel und erweiterbar, da du zusätzliche Bedingungen hinzufügen kannst, ohne bestehende Logik umzustrukturieren.

Einsatz im App Router

Im Gegensatz zum veralteten Pages Router ist die Middleware im App Router noch besser in den modernen Next.js-Workflow integriert. Middleware wird vor dem Rendering von Server Components oder API-Routen ausgeführt, was dir maximale Kontrolle über die Anfrageverarbeitung gibt.

Einsatzmöglichkeiten von Middleware

Middleware ist besonders effektiv, wenn es darum geht, Anfragen dynamisch zu analysieren und basierend darauf spezifische Aktionen auszuführen. Im Folgenden zeige ich dir drei gängige Einsatzszenarien: Authentifizierung, Logging und Feature Flags. Mit flexiblen if-Bedingungen kannst du diese Middleware-Anwendungsfälle einfach umsetzen und jederzeit erweitern.

1. Authentifizierung und Autorisierung

Ein häufiges Problem in Webanwendungen ist die Sicherstellung, dass nur authentifizierte Nutzer auf geschützte Bereiche zugreifen können. Mit Middleware kannst du eingehende Anfragen prüfen und Benutzer bei Bedarf weiterleiten.

Beispiel: Zugriff auf eine Admin-Seite nur für authentifizierte Nutzer

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

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/admin')) {
    const token = request.cookies.get('auth-token');
    if (!token) {
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }

  return NextResponse.next();
}

Erklärung:

• Hier wird geprüft, ob der angeforderte Pfad mit /admin beginnt.
• Wenn kein Authentifizierungs-Token vorhanden ist, wird der Nutzer auf die Login-Seite umgeleitet.
• Diese Struktur lässt sich leicht erweitern, z. B. um Benutzerrollen oder andere Zugriffsregeln zu berücksichtigen.

2. Logging und Analyse

Für viele Anwendungen ist es wichtig, eingehende Anfragen zu analysieren und zu protokollieren. Middleware kann genutzt werden, um diese Daten zu erfassen, bevor die Anfrage weiterverarbeitet wird.

Beispiel: Protokollieren von API-Anfragen

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api')) {
    console.log(`API-Anfrage: ${request.url} von IP: ${request.ip}`);
  }

  return NextResponse.next();
}

Erklärung:

• Alle Anfragen, die an /api-Routen gerichtet sind, werden geloggt.
• In diesem Beispiel werden die URL der Anfrage und die IP-Adresse protokolliert.
• Das Logging lässt sich leicht mit Tools wie Sentry oder LogRocket kombinieren, indem die Logs an externe APIs weitergeleitet werden.

3. Feature Flags

Möchtest du bestimmte Funktionen nur für ausgewählte Nutzer aktivieren? Feature Flags ermöglichen dir, neue Features gezielt auszurollen oder A/B-Tests durchzuführen.

Beispiel: Dynamische Umschreibung für Beta-Nutzer

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/feature')) {
    const isBetaUser = request.cookies.get('beta-user') === 'true';
    if (isBetaUser) {
      return NextResponse.rewrite(new URL('/beta', request.url));
    }
  }

  return NextResponse.next();
}

Erklärung:

• Wenn der angeforderte Pfad mit /feature beginnt, wird geprüft, ob der Nutzer ein Beta-Tester ist.
• Beta-Nutzer werden auf eine alternative Route /beta umgeleitet, während reguläre Nutzer die Standard-Funktionalität sehen.
• Dieses Konzept kann für A/B-Tests, geografische Zielgruppen oder schrittweise Feature-Rollouts angepasst werden.

Zusammenfassung Grundlagen der Middleware

Mit diesen drei Szenarien – Authentifizierung, Logging und Feature Flags – kannst du Middleware nutzen, um deine Anwendung sicherer, dynamischer und effizienter zu machen. Dank der flexiblen Struktur von if-Bedingungen kannst du beliebige Logik hinzufügen, ohne deine Middleware-Datei unübersichtlich zu gestalten.

Best Practices für Middleware

Middleware ist ein flexibles und leistungsstarkes Tool, doch es gibt einige bewährte Methoden, die dir helfen, sie effizient und übersichtlich einzusetzen. So vermeidest du Performance-Probleme und schaffst eine langfristig wartbare Struktur.

1. Eine zentrale middleware.ts-Datei

In einem Next.js-Projekt gibt es immer nur eine Middleware-Datei – middleware.ts oder middleware.js. Diese zentrale Datei wird bei jeder Anfrage ausgeführt, die Middleware nutzt. Um diese Datei flexibel und erweiterbar zu halten, empfiehlt es sich, Logik durch if-Bedingungen zu steuern:

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/admin')) {
    // Authentifizierungslogik
  }

  if (request.nextUrl.pathname.startsWith('/api')) {
    // Logging-Logik
  }

  if (request.nextUrl.pathname.startsWith('/feature')) {
    // Feature-Flag-Logik
  }

  return NextResponse.next();
}

Warum if-Bedingungen?

• Sie ermöglichen es, die Middleware einfach zu erweitern, indem neue Bedingungen hinzugefügt werden.
• Dadurch bleibt die Middleware-Datei flexibel, ohne dass Konfigurationen wie matcher ständig angepasst werden müssen.
• Das macht die Middleware besonders nützlich für Projekte mit vielen dynamischen Routen oder Anwendungsfällen.

2. Modularisierung der Logik

Je mehr Logik du in deiner Middleware einfügst, desto schneller kann sie unübersichtlich werden. Um das zu vermeiden, solltest du die einzelnen Logikblöcke auslagern, sobald deine middleware.ts-Datei zu groß wird.

Beispiel: Auslagern der Authentifizierungslogik

1. In der Middleware-Datei:

import { handleAdminAuth } from './lib/middleware/auth';  
import { logApiRequest } from './lib/middleware/logging';  

export function middleware(request: NextRequest) {  
  if (request.nextUrl.pathname.startsWith('/admin')) {  
    return handleAdminAuth(request);  
  }  
  if (request.nextUrl.pathname.startsWith('/api')) {  
    logApiRequest(request);  
  }  
  return NextResponse.next();  
}  

2. In der ausgelagerten Datei (lib/middleware/auth.ts):

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

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

Vorteile der Modularisierung:

• Deine Middleware bleibt übersichtlich und leicht verständlich.
• Die ausgelagerten Funktionen sind einfacher zu testen und zu warten.
• Änderungen an einer spezifischen Logik haben keinen Einfluss auf andere Bereiche.

3. Performance im Auge behalten

Da Middleware bei jeder Anfrage ausgeführt wird, ist es wichtig, sie leichtgewichtig und performant zu halten:

• Datenbankoperationen vermeiden: Führe keine direkten Datenbankabfragen in der Middleware aus. Nutze stattdessen Caching oder übergib die Anfragen an API-Handler.
• Schwere Berechnungen auslagern: Aufwendige Aufgaben sollten in Server Actions oder API-Routen verlagert werden.
• Nur relevante Anfragen prüfen: Verwende if-Bedingungen, um die Middleware auf spezifische Routen oder Bedingungen zu beschränken.

4. Klare Struktur und Namensgebung

• Benenne ausgelagerte Dateien und Funktionen klar und beschreibend, z. B. auth.ts für Authentifizierung oder logging.ts für Logging.
• Gruppiere verwandte Logik in Ordnern, z. B. lib/middleware.

Zusammenfassung Best Practices für Middleware

Die Middleware von Next.js ist mächtig, aber auch zentralisiert. Nutze if-Bedingungen, um sie flexibel und erweiterbar zu gestalten. Sobald die middleware.ts-Datei unübersichtlich wird, lagere die Logik in eigene Dateien aus, um die Wartbarkeit zu gewährleisten. Achte zudem darauf, dass deine Middleware schnell und leichtgewichtig bleibt, um die Performance deiner Anwendung nicht zu beeinträchtigen.

Im nächsten Abschnitt zeige ich dir, in welchen Situationen Middleware nicht geeignet ist und welche Alternativen du stattdessen nutzen kannst.

Limitierungen und Alternativen

Auch wenn Middleware in Next.js vielseitig einsetzbar ist, gibt es Szenarien, in denen sie nicht die optimale Lösung darstellt. Middleware ist für leichte und schnelle Prüfungen gedacht – für komplexere Aufgaben oder bestimmte Anforderungen gibt es bessere Alternativen.

Wann Middleware nicht geeignet ist

1. Direkte Datenbankoperationen: Middleware sollte nicht verwendet werden, um direkt mit einer Datenbank zu interagieren. Solche Operationen können zeitintensiv sein und die Middleware verlangsamen, was sich negativ auf die Nutzererfahrung auswirkt.
   Alternative: Führe Datenbankoperationen in Server Actions oder API-Handlern aus, die speziell dafür ausgelegt sind.
2. Schwere Berechnungen: Middleware wird bei jeder Anfrage ausgeführt, und lange Berechnungen können die Performance beeinträchtigen.
   Alternative: Verarbeite aufwendige Berechnungen entweder:
   • Asynchron im Hintergrund
   • Oder innerhalb von Server Actions, die spezifisch aufgerufen werden.
3. Komplexe Session-Verwaltung: Während Middleware Cookies oder Tokens überprüfen kann, ist sie nicht für die vollständige Verwaltung von Sessions ausgelegt. Middleware sollte nur einfache Prüfungen durchführen.
   Alternative: Nutze spezialisierte Authentifizierungsdienste wie Auth0, NextAuth.js oder Firebase, die Session-Handling direkt übernehmen.
4. Fehleranfällige Operationen: Middleware hat keinen Zugriff auf den vollen Node.js-Runtime-Stack. Wenn du Node-spezifische Funktionen benötigst, wie z. B. den Zugriff auf Dateisysteme oder bestimmte Node.js-Module, ist Middleware nicht geeignet, da sie im Edge Runtime-Umfeld ausgeführt wird.
   Alternative: Nutze Node.js-spezifische Operationen in API-Handlern oder anderen serverseitigen Funktionen.

Alternativen zur Middleware

1. Route Handler: Wenn du die volle Kontrolle über Anfragen und komplexe Logik benötigst, sind Route Handler in Next.js die bessere Wahl. Diese bieten Zugriff auf die gesamte Node.js-Runtime und eignen sich perfekt für:
   • Datenbankabfragen
   • Validierung von Payloads
   • Generierung dynamischer Inhalte
2. Server Actions: Server Actions sind eine moderne Lösung im App Router und ermöglichen es dir, serverseitige Logik nahtlos in deine React-Komponenten zu integrieren. Sie eignen sich hervorragend für:
   • Direkte Datenbankoperationen
   • Dynamische Datenabfragen
   • Formulare und interaktive Inhalte
3. Edge Functions: Für performante Operationen, die Middleware-ähnlich sind, kannst du auch auf Edge Functions setzen. Diese bieten zusätzliche Flexibilität, wenn du bestimmte Anforderungen direkt an der Edge umsetzen möchtest.

Zusammenfassung: Limitierungen und Alternativen

Middleware ist ein hervorragendes Werkzeug für leichte Prüfungen wie Authentifizierung, Logging oder Feature Flags. Sie stößt jedoch an ihre Grenzen, wenn es um komplexe Datenoperationen, aufwändige Berechnungen oder vollständige Session-Verwaltung geht. In solchen Fällen solltest du auf Alternativen wie Route Handler, Server Actions oder spezialisierte Dienste zurückgreifen. Indem du die Stärken und Schwächen von Middleware richtig einschätzt, kannst du die bestmögliche Architektur für deine Anwendung schaffen.

Fazit

Middleware in Next.js bietet dir eine elegante Möglichkeit, Anfragen dynamisch zu analysieren und anzupassen, bevor deine Anwendung reagiert. Besonders in Kombination mit dem App Router ermöglicht Middleware eine Vielzahl an Einsatzmöglichkeiten – von Authentifizierung über Logging bis hin zu Feature Flags.

Der größte Vorteil der Middleware liegt in ihrer zentralisierten Struktur: Mit nur einer Datei kannst du die gesamte Anfragenverarbeitung steuern. Durch die Verwendung von if-Bedingungen bleibt die Middleware flexibel und leicht erweiterbar, was sie besonders geeignet für komplexe Anwendungen macht. Gleichzeitig hilft dir die Auslagerung von Logik in separate Dateien, die Übersichtlichkeit und Wartbarkeit deiner Middleware zu bewahren.

Trotz ihrer Vielseitigkeit solltest du Middleware nicht für datenintensive oder komplexe Aufgaben einsetzen. Für solche Szenarien bieten sich Alternativen wie Route Handler, Server Actions oder spezialisierte Authentifizierungsdienste an.

Insgesamt ist Middleware ein unverzichtbares Werkzeug in deinem Next.js-Werkzeugkasten, das dir ermöglicht, deine Anwendung sicherer, effizienter und dynamischer zu gestalten. Nutze sie gezielt für die Bereiche, in denen sie ihre Stärken ausspielen kann – und kombiniere sie mit anderen Next.js-Features, um das Beste aus deiner Architektur herauszuholen.