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

cookies

cookies は非同期関数であり、Server ComponentでHTTPの着信リクエストのcookieを読み取ったり、Server ActionsまたはRoute Handlersで送信リクエストの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の範囲を制限します
secureBooleanHTTPS接続でのみcookieを送信して追加のセキュリティを確保します
httpOnlyBooleancookieをHTTPリクエストに限定し、クライアント側からのアクセスを防ぎます
sameSiteBoolean, 'lax', 'strict', 'none'cookieのクロスサイトリクエストの動作を制御します
priorityString ("low", "medium", "high")cookieの優先度を指定します
encode('value')Functioncookieの値をエンコードするために使用される関数を指定します
partitionedBooleancookieが分割されているかどうかを示します

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

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

知っておくべきこと​

  • cookies は非同期関数であり、Promiseを返します。cookieにアクセスするには async/await やReactのuse関数を使用する必要があります
    • バージョン14およびそれ以前では、cookiesは同期関数でした。互換性を保つために、Next.js 15でも同期的にアクセスできますが、この動作は将来的に非推奨となる予定です。
  • cookies は、その戻り値を事前に予測することができないDynamic APIです。これをレイアウトまたはページで使用すると、そのルートは動的レンダリングになります。
  • .delete メソッドは以下の場合にのみ呼び出すことができます
    • Server Action または Route Handler内
    • .set を呼び出したのと同じドメインに属する場合。また、削除したいcookieと同じプロトコル（HTTPまたはHTTPS）でコードを実行する必要があります。
  • HTTPはストリーミング開始後のcookie設定を許可しないため、Server ActionまたはRoute Handlerで.setを使用してください。

例​

(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 が導入されました