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

cookies

cookiesは、サーバーコンポーネントでHTTP受信リクエストのCookieを読み取ったり、サーバーアクションまたはルートハンドラで送信リクエストの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')ブーリアンCookie名を指定して、Cookieが存在するかどうかに基づいてブーリアンを返します。
set(name, value, options)-Cookie名、値、およびオプションを受け取り、送信リクエストのCookieを設定します。
delete(name)-Cookie名を指定してCookieを削除します。
clear()-すべてのCookieを削除します。
toString()文字列Cookieの文字列表現を返します。

オプション

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

オプション型説明
name文字列Cookieの名前を指定します。
value文字列Cookieに保存する値を指定します。
expires日付Cookieが期限切れになる正確な日付を定義します。
maxAge数値Cookieの有効期間を秒単位で設定します。
domain文字列Cookieが利用可能なドメインを指定します。
path文字列, デフォルト: '/'Cookieのスコープをドメイン内の特定のパスに制限します。
secureブーリアンセキュリティ向上のため、CookieがHTTPS接続経由でのみ送信されるようにします。
httpOnlyブーリアンCookieをHTTPリクエストに制限し、クライアントサイドからのアクセスを防止します。
sameSiteブーリアン, 'lax', 'strict', 'none'Cookieのクロスサイトリクエストの挙動を制御します。
priority文字列 ("low", "medium", "high")Cookieの優先度を指定します
encode('value')関数Cookieの値をエンコードするために使用される関数を指定します。
partitionedブーリアンCookieがパーティション化されているかどうかを示します。

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

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

知っておくと良いこと

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

サーバーコンポーネントでCookieを扱う際、Cookieが本質的にクライアントサイドのストレージメカニズムであることを理解することが重要です。

  • Cookieの読み取りは、クライアントのブラウザがHTTPリクエストヘッダーでサーバーに送信するCookieデータにアクセスするため、サーバーコンポーネントで機能します。
  • Cookieの設定は、ルートハンドラまたはサーバーアクションを使用している場合でも、サーバーコンポーネントで直接行うことはできません。これは、Cookieがサーバーではなくブラウザによって実際に保存されるためです。

サーバーは、ブラウザにCookieを保存するよう指示（Set-Cookieヘッダー経由）を送ることしかできません。実際の保存はクライアントサイドで行われます。これが、状態を変更するCookie操作（.set、.delete、.clear）を、レスポンスヘッダーが適切に設定できるルートハンドラまたはサーバーアクションで実行する必要がある理由です。

例

(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)メソッドを使用して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')
  // or
  cookieStore.set('name', 'lee', { secure: true })
  // or
  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が導入されました。