cookies

cookies — это асинхронная функция, которая позволяет читать входящие HTTP-куки в Server Components, а также читать/записывать исходящие куки в Server Actions или Route Handlers.

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

Справочник

Методы

Доступны следующие методы:

Метод	Возвращаемый тип	Описание
`get('name')`	Object	Принимает имя куки и возвращает объект с именем и значением.
`getAll()`	Array of objects	Возвращает список всех кук с совпадающим именем.
`has('name')`	Boolean	Принимает имя куки и возвращает boolean в зависимости от существования куки.
`set(name, value, options)`	-	Принимает имя куки, значение и опции, устанавливает исходящую куку.
`delete(name)`	-	Принимает имя куки и удаляет её.
`clear()`	-	Удаляет все куки.
`toString()`	String	Возвращает строковое представление кук.

Опции

При установке куки поддерживаются следующие свойства объекта options:

Опция	Тип	Описание
`name`	String	Указывает имя куки.
`value`	String	Указывает значение, хранимое в куке.
`expires`	Date	Определяет точную дату истечения срока действия куки.
`maxAge`	Number	Устанавливает срок жизни куки в секундах.
`domain`	String	Указывает домен, для которого доступна кука.
`path`	String, default: `'/'`	Ограничивает область действия куки определённым путём в домене.
`secure`	Boolean	Гарантирует отправку куки только через HTTPS-соединения для повышения безопасности.
`httpOnly`	Boolean	Ограничивает куку HTTP-запросами, предотвращая доступ на стороне клиента.
`sameSite`	Boolean, `'lax'`, `'strict'`, `'none'`	Управляет поведением куки при кросс-сайтовых запросах.
`priority`	String (`"low"`, `"medium"`, `"high"`)	Указывает приоритет куки.
`encode('value')`	Function	Указывает функцию для кодирования значения куки.
`partitioned`	Boolean	Указывает, является ли кука разделённой.

Единственная опция с значением по умолчанию — path.

Подробнее об этих опциях см. в документации MDN.

Полезно знать

cookies — это асинхронная функция, возвращающая промис. Для доступа к кукам необходимо использовать async/await или функцию use из React.
- В версии 14 и ранее cookies была синхронной функцией. Для обеспечения обратной совместимости в Next.js 15 её всё ещё можно использовать синхронно, но это поведение будет устаревшим в будущем.
cookies является Dynamic API, возвращаемые значения которого невозможно узнать заранее. Использование в layout или page переводит маршрут в динамический рендеринг.
Метод .delete может вызываться только:
- В Server Action или Route Handler.
- Если он принадлежит тому же домену, из которого вызывался .set. Для wildcard-доменов конкретный поддомен должен точно совпадать. Кроме того, код должен выполняться по тому же протоколу (HTTP или HTTPS), что и кука, которую нужно удалить.
HTTP не позволяет устанавливать куки после начала стриминга, поэтому .set необходимо использовать в Server Action или Route Handler.

Понимание поведения кук в Server Components

При работе с куками в Server Components важно понимать, что куки по своей природе являются механизмом хранения на стороне клиента:

Чтение кук работает в Server Components, потому что вы получаете доступ к данным кук, которые браузер клиента отправляет на сервер в заголовках HTTP-запроса.
Установка кук не может выполняться напрямую в Server Component, даже при использовании Route Handler или Server Action. Это связано с тем, что куки фактически хранятся браузером, а не сервером.

Сервер может только отправлять инструкции (через заголовки Set-Cookie), указывающие браузеру сохранить куки — фактическое хранение происходит на стороне клиента. Вот почему операции с куками, изменяющие состояние (.set, .delete, .clear), должны выполняться в Route Handler или Server Action, где можно правильно установить заголовки ответа.

Примеры

Получение куки

Метод (await cookies()).get('name') позволяет получить одну куку:

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

Получение всех кук

Метод (await cookies()).getAll() возвращает все куки с совпадающим именем. Если name не указан, возвращаются все доступные куки.

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

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

Установка куки

Метод (await cookies()).set(name, value, options) можно использовать в Server Action или Route Handler для установки куки. Объект options является необязательным.

'use server'

import { cookies } from 'next/headers'

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

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

'use server'

import { cookies } from 'next/headers'

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

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

Проверка существования куки

Метод (await cookies()).has(name) позволяет проверить существование куки:

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

Удаление кук

Есть три способа удалить куку.

Использование метода delete():

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

Установка новой куки с тем же именем и пустым значением:

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

Установка maxAge в 0 немедленно истекает срок действия куки. maxAge принимает значение в секундах.

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

История версий

Версия	Изменения
`v15.0.0-RC`	`cookies` теперь асинхронная функция. Доступен codemod.
`v13.0.0`	Добавлена функция `cookies`.

On this page