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

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')オブジェクトcookie の名前を指定してオブジェクト（名前と値）を返します。
getAll()オブジェクトの配列名前が一致するすべての 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ドメイン内の特定のパスに cookie の適用範囲を限定します。
secureBooleancookie を HTTPS 接続でのみ送信するようにし、セキュリティを強化します。
httpOnlyBooleancookie を HTTP リクエストに限定し、クライアント側からのアクセスを防ぎます。
sameSiteBoolean、'lax'、'strict'、'none'クロスサイトリクエスト時の cookie の挙動を制御します。
priorityString ("low", "medium", "high")cookie の優先度を指定します。
encode('value')Functioncookie の値をエンコードするための関数を指定します。
partitionedBooleancookie が partitioned かどうかを示します。

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

知っていると良い情報​

  • cookies は約束を返す 非同期 関数です。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 を使用する必要があります。

例​

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 の取得​

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

Server Action または Route Handler で cookies().set(name, value, options) メソッドを使用して 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: '/',
  })
}

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