Cookies

cookies ist eine asynchrone Funktion, die es ermöglicht, eingehende HTTP-Anfrage-Cookies in Server-Komponenten zu lesen sowie ausgehende Anfrage-Cookies in Server Actions oder Route Handlers zu lesen/schreiben.

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Referenz

Methoden

Folgende Methoden sind verfügbar:

Optionen

Beim Setzen eines Cookies werden folgende Eigenschaften im options-Objekt unterstützt:

Die einzige Option mit einem Standardwert ist path.

Weitere Informationen zu diesen Optionen finden Sie in den MDN-Dokumenten.

Wissenswertes

• cookies ist eine asynchrone Funktion, die ein Promise zurückgibt. Sie müssen async/await oder Reacts use-Funktion verwenden, um auf Cookies zuzugreifen.
  • In Version 14 und früher war cookies eine synchrone Funktion. Zur Abwärtskompatibilität ist der synchrone Zugriff in Next.js 15 noch möglich, wird aber in Zukunft veraltet sein.
• cookies ist eine dynamische API, deren Rückgabewerte nicht im Voraus bekannt sind. Die Verwendung in einem Layout oder einer Seite aktiviert dynamisches Rendering für die Route.
• Die .delete-Methode kann nur aufgerufen werden:
  • In einer Server Action oder einem Route Handler.
  • Wenn sie zur gleichen Domain gehört, von der .set aufgerufen wurde. Bei Wildcard-Domains muss die Subdomain exakt übereinstimmen. Zudem muss der Code über das gleiche Protokoll (HTTP oder HTTPS) ausgeführt werden wie der zu löschende Cookie.
• HTTP erlaubt das Setzen von Cookies nicht nach Beginn des Streamings. Daher muss .set in einer Server Action oder einem Route Handler verwendet werden.

Cookie-Verhalten in Server-Komponenten verstehen

Bei der Arbeit mit Cookies in Server-Komponenten ist wichtig zu verstehen, dass Cookies grundsätzlich ein Client-seitiger Speichermechanismus sind:

• Lesen von Cookies funktioniert in Server-Komponenten, weil auf die Cookie-Daten zugegriffen wird, die der Client-Browser in den HTTP-Request-Headern an den Server sendet.
• Setzen von Cookies kann nicht direkt in einer Server-Komponente erfolgen, auch nicht über Route Handler oder Server Actions. Cookies werden tatsächlich vom Browser gespeichert, nicht vom Server.

Der Server kann nur Anweisungen senden (via Set-Cookie-Header), um den Browser zum Speichern von Cookies anzuleiten - die tatsächliche Speicherung erfolgt Client-seitig. Daher müssen Cookie-Operationen, die den Zustand ändern (.set, .delete, .clear), in einem Route Handler oder einer Server Action durchgeführt werden, wo die Response-Header korrekt gesetzt werden können.

Beispiele

Cookie abrufen

Sie können die Methode (await cookies()).get('name') verwenden, um einen einzelnen Cookie abzurufen:

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Alle Cookies abrufen

Mit (await cookies()).getAll() können Sie alle Cookies mit passendem Namen abrufen. Wenn name nicht angegeben ist, werden alle verfügbaren Cookies zurückgegeben.

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

Cookie setzen

Die Methode (await cookies()).set(name, value, options) kann in einer Server Action oder einem Route Handler verwendet werden, um einen Cookie zu setzen. Das options-Objekt ist optional.

'use server'

import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()

  cookieStore.set('name', 'lee')
  // oder
  cookieStore.set('name', 'lee', { secure: true })
  // oder
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

Prüfen, ob ein Cookie existiert

Mit (await cookies()).has(name) können Sie prüfen, ob ein Cookie existiert:

import { cookies } from 'next/headers'

export default async function Page() {
  const cookieStore = await cookies()
  const hasCookie = cookieStore.has('theme')
  return '...'
}

Cookies löschen

Es gibt drei Möglichkeiten, einen Cookie zu löschen.

Verwendung der delete()-Methode:

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).delete('name')
}

Setzen eines neuen Cookies mit gleichem Namen und leerem Wert:

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).set('name', '')
}

Setzen von maxAge auf 0 lässt einen Cookie sofort ablaufen. maxAge akzeptiert einen Wert in Sekunden.

'use server'

import { cookies } from 'next/headers'

export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}

Versionsverlauf