コンテンツにスキップ
API リファレンス関数cookies

cookies

cookies は、Server Componentで HTTP の受信リクエストのクッキーを読み込み、Server Actions または Route Handlersで送信リクエストのクッキーを読み書きできる、非同期関数です。

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')Objectクッキー名を受け取り、名前と値を持つオブジェクトを返します。
getAll()オブジェクトの配列一致する名前のすべてのクッキーのリストを返します。
has('name')Booleanクッキー名を受け取り、クッキーが存在するかどうかに基づいてブール値を返します。
set(name, value, options)-クッキー名、値、オプションを受け取り、送信リクエストのクッキーを設定します。
delete(name)-クッキー名を受け取り、クッキーを削除します。
clear()-すべてのクッキーを削除します。
toString()Stringクッキーの文字列表現を返します。

オプション

クッキーを設定する際に、optionsオブジェクトの次のプロパティがサポートされています

オプション型説明
nameStringクッキーの名前を指定します。
valueStringクッキーに格納する値を指定します。
expiresDateクッキーが期限切れになる正確な日付を定義します。
maxAgeNumberクッキーの寿命を秒単位で設定します。
domainStringクッキーが利用可能なドメインを指定します。
pathStringクッキーのスコープをドメイン内の特定のパスに制限します。
secureBoolean,セキュリティ向上のため、クッキーが HTTPS 接続でのみ送信されるようにします。
httpOnlyBooleanクライアント側のアクセスを防ぎ、クッキーを HTTP リクエストに制限します。
sameSiteBoolean, 'lax', 'strict', 'none'クッキーのクロスサイトリクエストの動作を制御します。
priorityString ("low", "medium", "high")クッキーの優先度を指定します
encode('value')Functionクッキーの値をエンコードするために使用される関数を指定します。
partitionedBooleanクッキーが分割されているかどうかを示します。

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

知っておくと良いこと

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

例

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

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

すべてのクッキーの取得

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

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

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

app/actions.ts
'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: '/',
  })
}

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

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

クッキーの削除

クッキーを削除する方法は3つあります。

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

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

同じ名前で空の値を持つ新しいクッキーを設定する。

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

maxAge を 0 に設定すると、クッキーがすぐに期限切れになります。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 が導入されました。