NextRequest und NextResponse

next/server bietet server-exklusive Helfer für die Verwendung in Middleware und Edge-API-Routen.

NextRequest

Das NextRequest-Objekt erweitert die native Request-Schnittstelle mit folgenden zusätzlichen Methoden und Eigenschaften:

• cookies - Eine RequestCookies-Instanz mit Cookies aus der Request. Liest/verändert den Cookie-Header der Anfrage. Siehe auch Verwendung von Cookies in Middleware.

  • get - Eine Methode, die einen Cookie-name entgegennimmt und ein Objekt mit name und value zurückgibt. Falls kein Cookie mit dem name gefunden wird, gibt sie undefined zurück. Bei mehreren passenden Cookies wird nur der erste Treffer zurückgegeben.
  • getAll - Ähnlich wie get, gibt aber eine Liste aller Cookies mit passendem name zurück. Wenn name nicht angegeben ist, werden alle verfügbaren Cookies zurückgegeben.
  • set - Eine Methode, die ein Objekt mit Eigenschaften von CookieListItem gemäß der W3C CookieStore API-Spezifikation entgegennimmt.
  • delete - Eine Methode, die entweder einen Cookie-name oder eine Liste von Namen entgegennimmt und die passenden Cookies entfernt. Gibt true für gelöschte und false für nicht gelöschte Cookies zurück.
  • has - Eine Methode, die einen Cookie-name entgegennimmt und ein boolean zurückgibt, je nachdem ob der Cookie existiert (true) oder nicht (false).
  • clear - Eine Methode ohne Argumente, die effektiv den Cookie-Header entfernt.

• nextUrl: Enthält ein erweitertes, geparstes URL-Objekt mit Zugriff auf Next.js-spezifische Eigenschaften wie pathname, basePath, trailingSlash und i18n. Enthält folgende Eigenschaften:

  • basePath (string)
  • buildId (string || undefined)
  • defaultLocale (string || undefined)
  • domainLocale
    • defaultLocale: (string)
    • domain: (string)
    • http: (boolean || undefined)
    • locales: (string[] || undefined)
  • locale (string || undefined)
  • url (URL)

• ip: (string || undefined) - Enthält die IP-Adresse der Request. Diese Information wird von Ihrer Hosting-Plattform bereitgestellt.

• geo - Enthält die geografische Position der Request. Diese Information wird von Ihrer Hosting-Plattform bereitgestellt. Enthält folgende Eigenschaften:

  • city (string || undefined)
  • country (string || undefined)
  • region (string || undefined)
  • latitude (string || undefined)
  • longitude (string || undefined)

Sie können das NextRequest-Objekt als direkten Ersatz für die native Request-Schnittstelle verwenden, was Ihnen mehr Kontrolle über die Anfragebearbeitung gibt.

NextRequest kann aus next/server importiert werden:

import type { NextRequest } from 'next/server'

NextFetchEvent

Das NextFetchEvent-Objekt erweitert das native FetchEvent-Objekt und enthält die waitUntil()-Methode.

Die waitUntil()-Methode kann verwendet werden, um die Ausführung der Funktion zu verlängern, falls Sie weitere Hintergrundarbeiten durchführen müssen.

import { NextResponse } from 'next/server'
import type { NextFetchEvent, NextRequest } from 'next/server'

export function middleware(req: NextRequest, event: NextFetchEvent) {
  event.waitUntil(
    fetch('https://my-analytics-platform.com', {
      method: 'POST',
      body: JSON.stringify({ pathname: req.nextUrl.pathname }),
    })
  )

  return NextResponse.next()
}

Das NextFetchEvent-Objekt kann aus next/server importiert werden:

import type { NextFetchEvent } from 'next/server'

NextResponse

Die NextResponse-Klasse erweitert die native Response-Schnittstelle mit folgenden Elementen:

Öffentliche Methoden

Öffentliche Methoden sind auf einer Instanz der NextResponse-Klasse verfügbar. Je nach Anwendungsfall können Sie eine Instanz erstellen, einer Variable zuweisen und dann auf folgende öffentliche Methoden zugreifen:

• cookies - Eine ResponseCookies-Instanz mit den Cookies aus der Response. Liest/verändert den Set-Cookie-Header der Antwort. Siehe auch Verwendung von Cookies in Middleware.
  • get - Eine Methode, die einen Cookie-name entgegennimmt und ein Objekt mit name und value zurückgibt. Falls kein Cookie mit dem name gefunden wird, gibt sie undefined zurück. Bei mehreren passenden Cookies wird nur der erste Treffer zurückgegeben.
  • getAll - Ähnlich wie get, gibt aber eine Liste aller Cookies mit passendem name zurück. Wenn name nicht angegeben ist, werden alle verfügbaren Cookies zurückgegeben.
  • set - Eine Methode, die ein Objekt mit Eigenschaften von CookieListItem gemäß der W3C CookieStore API-Spezifikation entgegennimmt.
  • delete - Eine Methode, die entweder einen Cookie-name oder eine Liste von Namen entgegennimmt und die passenden Cookies entfernt. Gibt true für gelöschte und false für nicht gelöschte Cookies zurück.

Statische Methoden

Folgende statische Methoden sind direkt auf der NextResponse-Klasse verfügbar:

• redirect() - Gibt eine NextResponse mit gesetzter Weiterleitung zurück
• rewrite() - Gibt eine NextResponse mit gesetzter Umschreibung zurück
• next() - Gibt eine NextResponse zurück, die die Middleware-Kette fortsetzt

Um die oben genannten Methoden zu verwenden, müssen Sie das zurückgegebene NextResponse-Objekt zurückgeben. NextResponse kann aus next/server importiert werden:

import { NextResponse } from 'next/server'

userAgent

Der userAgent-Helfer ermöglicht die Interaktion mit dem User-Agent-Objekt der Anfrage. Es ist vom nativen Request-Objekt abstrahiert und ein Opt-in-Feature. Es hat folgende Eigenschaften:

• isBot: (boolean) Gibt an, ob die Anfrage von einem bekannten Bot stammt
• browser
  • name: (string || undefined) Der Name des Browsers
  • version: (string || undefined) Die Version des Browsers, dynamisch bestimmt
• device
  • model: (string || undefined) Das Modell des Geräts, dynamisch bestimmt
  • type: (string || undefined) Der Typ des Browsers, kann einer der folgenden Werte sein: console, mobile, tablet, smarttv, wearable, embedded oder undefined
  • vendor: (string || undefined) Der Hersteller des Geräts, dynamisch bestimmt
• engine
  • name: (string || undefined) Der Name der Browser-Engine, mögliche Werte: Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit oder undefined
  • version: (string || undefined) Die Version der Browser-Engine, dynamisch bestimmt, oder undefined
• os
  • name: (string || undefined) Der Name des Betriebssystems, kann undefined sein
  • version: (string || undefined) Die Version des Betriebssystems, dynamisch bestimmt, oder undefined
• cpu
  • architecture: (string || undefined) Die Architektur der CPU, mögliche Werte: 68k, amd64, arm, arm64, armhf, avr, ia32, ia64, irix, irix64, mips, mips64, pa-risc, ppc, sparc, sparc64 oder undefined

userAgent kann aus next/server importiert werden:

import { userAgent } from 'next/server'

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

export function middleware(request: NextRequest) {
  const url = request.nextUrl
  const { device } = userAgent(request)
  const viewport = device.type === 'mobile' ? 'mobile' : 'desktop'
  url.searchParams.set('viewport', viewport)
  return NextResponse.rewrite(url)
}

FAQ

Warum verwendet redirect 307 und 308?

Bei der Verwendung von redirect() fällt auf, dass die Statuscodes 307 für eine temporäre Weiterleitung und 308 für eine permanente Weiterleitung verwendet werden. Traditionell wurde 302 für temporäre und 301 für permanente Weiterleitungen verwendet, jedoch haben viele Browser die Anfragemethode der Weiterleitung von POST zu GET geändert, wenn ein 302 verwendet wurde, unabhängig von der ursprünglichen Anfragemethode.

Nehmen wir das Beispiel einer Weiterleitung von /users zu /people: Wenn Sie eine POST-Anfrage an /users senden, um einen neuen Benutzer zu erstellen, und eine 302-temporäre Weiterleitung erfolgt, wird die Anfragemethode von POST zu GET geändert. Das ergibt keinen Sinn, da zum Erstellen eines neuen Benutzers eine POST-Anfrage an /people gesendet werden sollte, nicht eine GET-Anfrage.

Die Einführung des 307-Statuscodes bedeutet, dass die Anfragemethode als POST beibehalten wird.

• 302 - Temporäre Weiterleitung, ändert die Anfragemethode von POST zu GET
• 307 - Temporäre Weiterleitung, behält die Anfragemethode als POST bei

Die redirect()-Methode verwendet standardmäßig 307 anstelle von 302 für temporäre Weiterleitungen, was bedeutet, dass Ihre Anfragen immer als POST-Anfragen beibehalten werden.

Wenn Sie eine GET-Antwort auf eine POST-Anfrage auslösen möchten, verwenden Sie 303.

Erfahren Sie mehr über HTTP-Weiterleitungen.

Wie greife ich auf Umgebungsvariablen zu?

process.env kann verwendet werden, um auf Umgebungsvariablen aus Edge-Middleware zuzugreifen. Sie werden während next build ausgewertet: