cookies

cookies は非同期関数で、Server Components で HTTP 受信リクエストのクッキーを読み取ったり、Server Actions または Route Handlers で送信リクエストのクッキーを読み書きしたりできます。

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

リファレンス

メソッド

以下のメソッドが利用可能です。

オプション

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

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

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

補足

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

Server Components でのクッキー動作の理解

Server Components でクッキーを使用する場合、クッキーは根本的にクライアント側のストレージメカニズムであることを理解することが重要です。

• クッキーの読み取りは、クライアントのブラウザが HTTP リクエストヘッダーでサーバーに送信するクッキーデータにアクセスしているため、Server Components で機能します。
• クッキーの設定は、Route Handler または Server Action を使用している場合でも、Server Component 直接では実行できません。これは、クッキーが実際にはサーバーではなくブラウザによって保存されるためです。

サーバーは、ブラウザにクッキーを保存するよう指示するための命令（Set-Cookie ヘッダー経由）を送信できるだけで、実際のストレージはクライアント側で発生します。そのため、状態を変更するクッキー操作（.set、.delete、.clear）は、レスポンスヘッダーを適切に設定できる Route Handler または Server Action で実行する必要があります。

Server Actions でのクッキー動作の理解

Server Action でクッキーを設定または削除した後、Next.js はサーバー上で現在のページとそのレイアウトを再レンダリングして、UI が新しいクッキー値を反映するようにします。キャッシングガイドを参照してください。

UI はアンマウントされませんが、サーバーから取得するデータに依存するエフェクトは再実行されます。

キャッシュされたデータも更新するには、アクション内で revalidatePath または revalidateTag を呼び出してください。

例

クッキーの取得

(await cookies()).get('name') メソッドを使用して単一のクッキーを取得できます。

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

すべてのクッキーの取得

(await cookies()).getAll() メソッドを使用してすべてのクッキーを取得できます。名前を指定しない場合、利用可能なすべてのクッキーを返します。

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

クッキーの設定

Server Action または Route Handler で (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: '/',
  })
}

クッキーの存在確認

(await cookies()).has(name) メソッドを使用してクッキーが存在するかどうかを確認できます。

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()).set('name', '')
}

maxAge を 0 に設定するとクッキーが即座に有効期限切れになります。maxAge は秒単位の値を受け入れます。

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

バージョン履歴