メインコンテンツまでスキップ

cookies

cookiesは、server componentでHTTPの受信リクエストのcookieを読み取るための非同期関数であり、server actionsやroute handlerで送信リクエストのcookieを読み書きするためのものです。

app/page.tsx
import { cookies } from 'next/headers'

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

リファレンス​

メソッド​

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

メソッド戻り値の型説明
get('name')Objectcookie名を受け取り、その名前と値を持つオブジェクトを返します。
getAll()Array of objects一致する名前を持つすべてのcookieのリストを返します。
has('name')Booleancookie名を受け取り、cookieが存在するかどうかに基づいてブール値を返します。
set(name, value, options)-cookie名、値、およびオプションを受け取り、送信リクエストのcookieを設定します。
delete(name)-cookie名を受け取り、cookieを削除します。
clear()-すべてのcookieを削除します。
toString()Stringcookieの文字列表現を返します。

オプション​

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

オプション型説明
nameStringcookieの名前を指定します。
valueStringcookieに格納される値を指定します。
expiresDatecookieが失効する正確な日付を定義します。
maxAgeNumbercookieの寿命を秒単位で設定します。
domainStringcookieが利用可能なドメインを指定します。
pathString, default: '/'ドメイン内の特定のパスにcookieの範囲を制限します。
secureBoolean追加のセキュリティのために、cookieがHTTPS接続でのみ送信されることを保証します。
httpOnlyBooleancookieをHTTPリクエストに限定し、クライアント側のアクセスを防ぎます。
sameSiteBoolean, 'lax', 'strict', 'none'cookieのクロスサイトリクエストの動作を制御します。
priorityString ("low", "medium", "high")cookieの優先度を指定します。
encode('value')Functioncookieの値をエンコードするために使用される関数を指定します。
partitionedBooleancookieがpartitionedであるかどうかを示します。

デフォルト値が設定されている唯一のオプションはpathです。

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

Good to know​

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

server componentでcookieを扱う際には、cookieが基本的にクライアント側のストレージメカニズムであることを理解することが重要です：

  • cookieの読み取りは、クライアントのブラウザがサーバーに送信するHTTPリクエストヘッダーのcookieデータにアクセスするため、server componentで動作します。
  • cookieの設定は、route handlerやserver actionを使用しても、server component内で直接行うことはできません。これは、cookieが実際にはサーバーではなくブラウザによって保存されるためです。

サーバーは、ブラウザにcookieを保存するよう指示するためのSet-Cookieヘッダーを送信することしかできません。実際の保存はクライアント側で行われます。このため、状態を変更するcookie操作（.set、.delete、.clear）は、レスポンスヘッダーを適切に設定できるroute handlerやserver actionで実行する必要があります。

例​

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

app/page.tsx
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を返します。

app/page.tsx
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でcookieを設定できます。optionsオブジェクトはオプションです。

app/actions.ts
'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)メソッドを使用して、cookieが存在するかどうかを確認できます：

app/page.ts
import { cookies } from 'next/headers'

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

cookieを削除する​

cookieを削除する方法は3つあります。

delete()メソッドを使用する：

app/actions.ts
'use server'

import { cookies } from 'next/headers'

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

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

app/actions.ts
'use server'

import { cookies } from 'next/headers'

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

maxAgeを0に設定すると、cookieは即座に失効します。maxAgeは秒単位の値を受け入れます。

app/actions.ts
'use server'

import { cookies } from 'next/headers'

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

バージョン履歴​

バージョン変更点
v15.0.0-RCcookiesは非同期関数になりました。codemodが利用可能です。
v13.0.0cookiesが導入されました。