cookies

cookies est une fonction asynchrone qui vous permet de lire les cookies des requêtes HTTP entrantes dans les Composants Serveur, et de lire/écrire les cookies des requêtes sortantes dans les Actions Serveur ou les Gestionnaires de Route.

import { cookies } from 'next/headers'

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

Référence

Méthodes

Les méthodes suivantes sont disponibles :

Options

Lors de la définition d'un cookie, les propriétés suivantes de l'objet options sont supportées :

La seule option avec une valeur par défaut est path.

Pour en savoir plus sur ces options, consultez la documentation MDN.

Bon à savoir

• cookies est une fonction asynchrone qui retourne une promesse. Vous devez utiliser async/await ou la fonction use de React pour accéder aux cookies.
  • Dans la version 14 et antérieures, cookies était une fonction synchrone. Pour assurer la compatibilité ascendante, vous pouvez toujours y accéder de manière synchrone dans Next.js 15, mais ce comportement sera déprécié à l'avenir.
• cookies est une API Dynamique dont les valeurs retournées ne peuvent pas être connues à l'avance. Son utilisation dans une mise en page ou une page activera le rendu dynamique pour la route.
• La méthode .delete ne peut être appelée que :
  • Dans une Action Serveur ou un Gestionnaire de Route.
  • Si elle appartient au même domaine depuis lequel .set a été appelé. Pour les domaines génériques, le sous-domaine spécifique doit correspondre exactement. De plus, le code doit être exécuté sur le même protocole (HTTP ou HTTPS) que le cookie que vous souhaitez supprimer.
• HTTP ne permet pas de définir des cookies après le début du streaming, vous devez donc utiliser .set dans une Action Serveur ou un Gestionnaire de Route.

Comprendre le comportement des cookies dans les Composants Serveur

Lorsque vous travaillez avec des cookies dans les Composants Serveur, il est important de comprendre que les cookies sont fondamentalement un mécanisme de stockage côté client :

• Lire les cookies fonctionne dans les Composants Serveur car vous accédez aux données de cookie que le navigateur du client envoie au serveur dans les en-têtes de requête HTTP.
• Définir des cookies ne peut pas être fait directement dans un Composant Serveur, même en utilisant un Gestionnaire de Route ou une Action Serveur. Cela s'explique par le fait que les cookies sont en réalité stockés par le navigateur, pas par le serveur.

Le serveur ne peut qu'envoyer des instructions (via les en-têtes Set-Cookie) pour indiquer au navigateur de stocker les cookies - le stockage réel a lieu côté client. C'est pourquoi les opérations sur les cookies qui modifient l'état (.set, .delete, .clear) doivent être effectuées dans un Gestionnaire de Route ou une Action Serveur où les en-têtes de réponse peuvent être correctement définis.

Exemples

Obtenir un cookie

Vous pouvez utiliser la méthode (await cookies()).get('nom') pour obtenir un seul cookie :

import { cookies } from 'next/headers'

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

Obtenir tous les cookies

Vous pouvez utiliser la méthode (await cookies()).getAll() pour obtenir tous les cookies correspondant à un nom. Si nom n'est pas spécifié, elle retourne tous les cookies disponibles.

import { cookies } from 'next/headers'

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

Définir un cookie

Vous pouvez utiliser la méthode (await cookies()).set(nom, valeur, options) dans une Action Serveur ou un Gestionnaire de Route pour définir un cookie. L'objet options est facultatif.

'use server'

import { cookies } from 'next/headers'

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

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

Vérifier si un cookie existe

Vous pouvez utiliser la méthode (await cookies()).has(nom) pour vérifier si un cookie existe :

import { cookies } from 'next/headers'

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

Supprimer des cookies

Il existe trois façons de supprimer un cookie.

En utilisant la méthode delete() :

'use server'

import { cookies } from 'next/headers'

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

En définissant un nouveau cookie avec le même nom et une valeur vide :

'use server'

import { cookies } from 'next/headers'

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

Définir maxAge à 0 expire immédiatement un cookie. maxAge accepte une valeur en secondes.

'use server'

import { cookies } from 'next/headers'

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

Historique des versions