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

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 のスコープを制限します。
secureBoolean追加のセキュリティのために cookie を HTTPS 接続でのみ送信することを保証します。
httpOnlyBooleancookie を HTTP リクエストに制限し、クライアント側のアクセスを防ぎます。
sameSiteBoolean, 'lax', 'strict', 'none'cookie のクロスサイトリクエストの動作を制御します。
priorityString ("low", "medium", "high")cookie の優先度を指定します
encode('value')Functioncookie の値をエンコードするために使用される関数を指定します。
partitionedBooleancookie が分割されているかどうかを示します。

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

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

Good to know​

  • 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 を使用する必要があります。

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