logoNext.js 日本語
ドキュメントブログ学習
はじめに/API リファレンス/関数/cookies

cookies

cookies は非同期（async）関数で、サーバーコンポーネントで HTTP 受信リクエストのクッキーを読み取ったり、サーバーアクションやルートハンドラで送信リクエストのクッキーを読み書きしたりできます。

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')オブジェクトクッキー名を受け取り、名前と値を持つオブジェクトを返します。
getAll()オブジェクトの配列一致する名前のすべてのクッキーのリストを返します。
has('name')ブール値クッキー名を受け取り、クッキーが存在するかどうかを示す値を返します。
set(name, value, options)-クッキー名、値、オプションを受け取り、送信リクエストのクッキーを設定します。
delete(name)-クッキー名を受け取り、クッキーを削除します。
clear()-すべてのクッキーを削除します。
toString()文字列クッキーの文字列表現を返します。

オプション

クッキーを設定する際、options オブジェクトの以下のプロパティがサポートされています：

オプション型説明
name文字列クッキーの名前を指定します。
value文字列クッキーに保存する値を指定します。
expiresDateクッキーが期限切れになる正確な日時を定義します。
maxAge数値クッキーの有効期間を秒単位で設定します。
domain文字列クッキーが利用可能なドメインを指定します。
path文字列（デフォルト: '/'）クッキーの適用範囲をドメイン内の特定のパスに制限します。
secureブール値HTTPS 接続でのみクッキーを送信するようにします（セキュリティ向上）。
httpOnlyブール値クッキーを HTTP リクエストに制限し、クライアント側からのアクセスを防ぎます。
sameSiteブール値、'lax'、'strict'、'none'クッキーのクロスサイトリクエスト動作を制御します。
priority文字列（"low"、"medium"、"high"）クッキーの優先度を指定します。
encode('value')関数クッキーの値をエンコードする関数を指定します。
partitionedブール値クッキーがパーティション化されているかどうかを示します。

デフォルト値を持つ唯一のオプションは path です。

これらのオプションの詳細については、MDN ドキュメントを参照してください。

知っておくと便利な情報

  • cookies は非同期関数で、Promise を返します。クッキーにアクセスするには async/await または React の use 関数を使用する必要があります。
    • バージョン 14 以前では、cookies は同期関数でした。後方互換性のために Next.js 15 でも同期的にアクセスできますが、この動作は将来的に非推奨になります。
  • cookies はダイナミック API で、返される値を事前に知ることはできません。レイアウトやページで使用すると、ルートは動的レンダリングに切り替わります。
  • .delete メソッドは以下の場合にのみ呼び出せます：
    • サーバーアクションまたはルートハンドラ内
    • .set が呼び出されたのと同じドメインに属している場合。ワイルドカードドメインの場合、特定のサブドメインが完全に一致する必要があります。また、コードは削除したいクッキーと同じプロトコル（HTTP または HTTPS）で実行される必要があります。
  • HTTP はストリーミング開始後にクッキーを設定することを許可していないため、サーバーアクションまたはルートハンドラで .set を使用する必要があります。

サーバーコンポーネントでのクッキー動作の理解

サーバーコンポーネントでクッキーを扱う際、クッキーが本質的にクライアントサイドのストレージメカニズムであることを理解することが重要です：

  • クッキーの読み取りは、クライアントのブラウザが HTTP リクエストヘッダーでサーバーに送信するクッキーデータにアクセスするため、サーバーコンポーネントで動作します。
  • クッキーの設定は、ルートハンドラやサーバーアクションを使用している場合でも、サーバーコンポーネントでは直接行えません。これはクッキーが実際にはサーバーではなくブラウザに保存されるためです。

サーバーはブラウザにクッキーを保存するよう指示（Set-Cookie ヘッダー経由）を送ることしかできません - 実際の保存はクライアントサイドで行われます。これが、状態を変更するクッキー操作（.set、.delete、.clear）がレスポンスヘッダーを適切に設定できるルートハンドラまたはサーバーアクションで実行されなければならない理由です。

使用例

クッキーの取得

(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>名前: {cookie.name}</p>
      <p>値: {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>名前: {cookie.name}</p>
      <p>値: {cookie.value}</p>
    </div>
  ))
}

クッキーの設定

サーバーアクションまたはルートハンドラで (await cookies()).set(name, value, options) メソッドを使用してクッキーを設定できます。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 '...'
}

クッキーの削除

クッキーを削除する方法は3つあります。

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-RCcookies が非同期関数になりました。コードモッドが利用可能です。
v13.0.0cookies が導入されました。

connection

connection関数のAPIリファレンス。

draftMode

draftMode 関数の API リファレンス。