Cookies

cookies ist eine asynchrone Funktion, die es Ihnen ermöglicht, HTTP-Anfrage-Cookies in Server-Komponenten zu lesen sowie ausgehende Anfrage-Cookies in Server-Aktionen oder Route-Handlern zu lesen und zu schreiben.

app/page.tsx

TypeScript

import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

app/page.js

import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Referenz

Methoden

Die folgenden Methoden stehen zur Verfügung:

Methode	Rückgabetyp	Beschreibung
`get('name')`	Objekt	Akzeptiert einen Cookie-Namen und gibt ein Objekt mit Namen und Wert zurück.
`getAll()`	Array von Objekten	Gibt eine Liste aller Cookies mit einem übereinstimmenden Namen zurück.
`has('name')`	Boolesch	Akzeptiert einen Cookie-Namen und gibt einen booleschen Wert zurück, ob der Cookie existiert.
`set(name, value, options)`	-	Akzeptiert einen Cookie-Namen, Wert und Optionen und setzt den ausgehenden Anfrage-Cookie.
`delete(name)`	-	Akzeptiert einen Cookie-Namen und löscht den Cookie.
`clear()`	-	Löscht alle Cookies.
`toString()`	String	Gibt eine Zeichenkettenrepräsentation der Cookies zurück.

Optionen

Beim Setzen eines Cookies werden die folgenden Eigenschaften aus dem options-Objekt unterstützt:

Option	Typ	Beschreibung
`name`	String	Legt den Namen des Cookies fest.
`value`	String	Legt den im Cookie zu speichernden Wert fest.
`expires`	Datum	Definiert das genaue Datum, an dem der Cookie abläuft.
`maxAge`	Zahl	Setzt die Lebensdauer des Cookies in Sekunden.
`domain`	String	Gibt die Domain an, in der der Cookie verfügbar ist.
`path`	String	Begrenzt den Geltungsbereich des Cookies auf einen bestimmten Pfad innerhalb der Domain.
`secure`	Boolesch	Stellt sicher, dass der Cookie nur über HTTPS-Verbindungen gesendet wird.
`httpOnly`	Boolesch	Beschränkt den Cookie auf HTTP-Anfragen und verhindert den Zugriff auf Clientseite.
`sameSite`	Boolesch, `'lax'`, `'strict'`, `'none'`	Steuert das domainübergreifende Anfrageverhalten des Cookies.
`priority`	String (`"low"`, `"medium"`, `"high"`)	Legt die Priorität des Cookies fest.
`encode('value')`	Funktion	Legt eine Funktion fest, die zum Encodieren des Cookie-Wertes verwendet wird.
`partitioned`	Boolesch	Gibt an, ob der Cookie partitioniert ist.

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

Hinweis

cookies ist eine asynchrone Funktion, die ein Promise zurückgibt. Sie müssen async/await oder die use-Funktion von React verwenden, um auf Cookies zuzugreifen.
- In Version 14 und früher war cookies eine synchrone Funktion. Zur Rückwärtskompatibilität können Sie in Next.js 15 noch synchron darauf zugreifen, aber dieses Verhalten wird in Zukunft als veraltet markiert.
cookies ist eine dynamische API, deren Rückgabewerte nicht im Voraus bekannt sein können. Die Verwendung in einem Layout oder einer Seite führt zu dynamischem Rendering.
Die .delete-Methode kann nur aufgerufen werden:
- In einer Server-Aktion oder einem Route-Handler.
- Wenn er zur selben Domain gehört, von der aus .set aufgerufen wird. Zusätzlich muss der Code auf demselben Protokoll (HTTP oder HTTPS) ausgeführt werden wie der zu löschende Cookie.
HTTP erlaubt das Setzen von Cookies nicht, nachdem das Streaming gestartet ist. Daher müssen Sie .set in einer Server-Aktion oder einem Route-Handler verwenden.

Beispiele

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

app/page.tsx

TypeScript

import { cookies } from 'next/headers'
 
export default async function Page() {
  const cookieStore = await cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

Alle Cookies auslesen

Sie können die Methode cookies().getAll() verwenden, um alle Cookies mit einem übereinstimmenden Namen zu erhalten. Wenn name nicht angegeben ist, werden alle verfügbaren Cookies zurückgegeben.

app/page.tsx

TypeScript

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>
  ))
}

Sie können die Methode cookies().set(name, value, options) in einer Server-Aktion oder einem Route-Handler verwenden, um einen Cookie zu setzen. Das options-Objekt ist optional.

app/actions.ts

TypeScript

'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: '/',
  })
}

app/actions.js

'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: '/',
  })
}

Du kannst die Methode cookies().has(name) verwenden, um zu überprüfen, ob ein Cookie existiert:

app/page.ts

TypeScript

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

Löschen von Cookies

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

Verwenden der delete()-Methode:

app/actions.ts

TypeScript

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

app/actions.js

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

Setzen eines neuen Cookies mit dem gleichen Namen und einem leeren Wert:

app/actions.ts

TypeScript

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', '')
}

app/actions.js

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', '')
}

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

app/actions.ts

TypeScript

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}

app/actions.js

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).set('name', 'value', { maxAge: 0 })
}

Versionshistorie

Version	Änderungen
`v15.0.0-RC`	`cookies` ist jetzt eine asynchrone Funktion. Ein Codemod ist verfügbar.
`v13.0.0`	`cookies` eingeführt.