cookies

cookies es una función asíncrona que permite leer las cookies de solicitudes HTTP entrantes en Componentes del Servidor, y leer/escribir cookies de solicitudes salientes en Acciones del Servidor o Manejadores de Ruta.

import { cookies } from 'next/headers'

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

Referencia

Métodos

Los siguientes métodos están disponibles:

Opciones

Al establecer una cookie, se admiten las siguientes propiedades del objeto opciones:

La única opción con valor predeterminado es path.

Para más información sobre estas opciones, consulta la documentación de MDN.

Bueno saber

• cookies es una función asíncrona que devuelve una promesa. Debes usar async/await o la función use de React para acceder a las cookies.
  • En la versión 14 y anteriores, cookies era una función síncrona. Para mantener compatibilidad, aún puedes accederla sincrónicamente en Next.js 15, pero este comportamiento se desaprobará en el futuro.
• cookies es una API Dinámica cuyos valores no pueden conocerse de antemano. Usarla en un layout o página activará renderizado dinámico.
• El método .delete solo puede llamarse:
  • En una Acción del Servidor o Manejador de Ruta.
  • Si pertenece al mismo dominio desde donde se llamó a .set. Para dominios comodín, el subdominio específico debe coincidir exactamente. Además, el código debe ejecutarse en el mismo protocolo (HTTP o HTTPS) que la cookie a eliminar.
• HTTP no permite establecer cookies después de iniciar streaming, por lo que debes usar .set en una Acción del Servidor o Manejador de Ruta.

Entendiendo el Comportamiento de Cookies en Componentes del Servidor

Al trabajar con cookies en Componentes del Servidor, es importante entender que las cookies son fundamentalmente un mecanismo de almacenamiento del lado del cliente:

• Leer cookies funciona en Componentes del Servidor porque accedes a los datos que el navegador envía al servidor en los encabezados HTTP.
• Establecer cookies no puede hacerse directamente en un Componente del Servidor, incluso usando un Manejador de Ruta o Acción del Servidor. Esto porque las cookies se almacenan en el navegador, no en el servidor.

El servidor solo puede enviar instrucciones (vía encabezados Set-Cookie) para indicar al navegador que almacene cookies - el almacenamiento real ocurre en el cliente. Por esto, las operaciones que modifican estado (.set, .delete, .clear) deben realizarse en un Manejador de Ruta o Acción del Servidor donde se pueden configurar los encabezados de respuesta adecuadamente.

Ejemplos

Obteniendo una cookie

Puedes usar el método (await cookies()).get('nombre') para obtener una cookie individual:

import { cookies } from 'next/headers'

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

Obteniendo todas las cookies

Puedes usar (await cookies()).getAll() para obtener todas las cookies con nombre coincidente. Si no se especifica nombre, devuelve todas las 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>Nombre: {cookie.name}</p>
      <p>Valor: {cookie.value}</p>
    </div>
  ))
}

Estableciendo una cookie

Puedes usar (await cookies()).set(nombre, valor, opciones) en una Acción del Servidor o Manejador de Ruta para establecer una cookie. El objeto opciones es opcional.

'use server'

import { cookies } from 'next/headers'

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

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

Verificando si existe una cookie

Puedes usar (await cookies()).has(nombre) para verificar si una cookie existe:

import { cookies } from 'next/headers'

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

Eliminando cookies

Hay tres formas de eliminar una cookie.

Usando el método delete():

'use server'

import { cookies } from 'next/headers'

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

Estableciendo una nueva cookie con el mismo nombre y valor vacío:

'use server'

import { cookies } from 'next/headers'

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

Estableciendo maxAge a 0 expirará la cookie inmediatamente. maxAge acepta un valor en segundos.

'use server'

import { cookies } from 'next/headers'

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

Historial de Versiones