cookies

cookies は、サーバーコンポーネントでHTTPリクエストのCookieを読み取るための **非同期** 関数です。また、サーバーアクションまたはルートハンドラーでアウトゴーイングリクエストのCookieを読み書きすることもできます。

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

リファレンス

メソッド

利用可能なメソッドは以下の通りです。

オプション

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

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

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

Good to know

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

サーバーコンポーネントにおけるCookieの動作の理解

サーバーコンポーネントでCookieを扱う場合、Cookieは基本的にクライアントサイドのストレージメカニズムであることを理解することが重要です。

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

サーバーは、ブラウザにCookieを保存するように指示する（Set-Cookieヘッダー経由で）ことしかできません。実際の保存はクライアント側で行われます。そのため、状態を変更するCookie操作（.set、.delete、.clear）は、レスポンスヘッダーを正しく設定できるルートハンドラーまたはサーバーアクションで行う必要があります。

サーバーアクションにおけるCookieの動作の理解

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

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

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

例

Cookieの取得

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

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

すべてのCookieの取得

(await cookies()).getAll() メソッドを使用して、指定された名前と一致するすべてのCookieを取得できます。name が指定されていない場合、利用可能なすべてのCookieが返されます。

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

Cookieの設定

(await cookies()).set(name, value, options) メソッドをサーバーアクションまたはルートハンドラーで使用して、Cookieを設定できます。options オブジェクトはオプションです。

'use server'
 
import { cookies } from 'next/headers'
 
export async function create(data) {
  const cookieStore = await cookies()
 
  cookieStore.set('name', 'lee')
  // or
  cookieStore.set('name', 'lee', { secure: true })
  // or
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

Cookieの存在確認

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

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

Cookieの削除

Cookieを削除するには3つの方法があります。

delete() メソッドの使用

'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

同じ名前で空の値を持つ新しいCookieを設定する

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

maxAgeを0に設定すると、Cookieは直ちに期限切れになります。maxAgeは秒単位の値を受け取ります。

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

バージョン履歴