Sponsor
ChatHubChatHub — Use GPT-4, Gemini, Claude 3.5 and more chatbots side-by-side
ここをクリック
Menu

cookies

cookies は 非同期 関数で、サーバーコンポーネントで HTTP 受信リクエストのクッキーを読み取り、サーバーアクションまたはルートハンドラーで送信リクエストのクッキーを読み書きすることができます。

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

リファレンス

メソッド

以下のメソッドが利用可能です：

メソッド戻り値説明
get('name')オブジェクトクッキー名を受け取り、名前と値を含むオブジェクトを返します。
getAll()オブジェクトの配列一致する名前を持つすべてのクッキーのリストを返します。
has('name')真偽値クッキー名を受け取り、クッキーが存在するかどうかに基づいて真偽値を返します。
set(name, value, options)-クッキー名、値、オプションを受け取り、送信リクエストのクッキーを設定します。
delete(name)-クッキー名を受け取り、クッキーを削除します。
clear()-すべてのクッキーを削除します。
toString()文字列クッキーの文字列表現を返します。

オプション

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

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

デフォルト値があるオプションは path のみです。

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

補足

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

サーバーコンポーネントでのクッキーの動作について

サーバーコンポーネントでクッキーを扱う際には、クッキーが基本的にクライアント側のストレージメカニズムであることを理解しておくことが重要です：

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

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

例

クッキーの取得

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

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

すべてのクッキーの取得

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

app/page.tsx
TypeScript
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)メソッドを使用してクッキーを設定できます。optionsオブジェクトはオプションです。

app/actions.ts
TypeScript
'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) メソッドを使用して、クッキーが存在するかどうかを確認できます：

app/page.ts
TypeScript
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
TypeScript
'use server'
 
import { cookies } from 'next/headers'
 
export async function delete(data) {
  (await cookies()).delete('name')
}

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

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

maxAge を 0 に設定すると、クッキーは直ちに期限切れになります。maxAge は秒単位の値を受け取ります。

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

バージョン履歴

バージョン変更点
v15.0.0-RCcookies は非同期関数になりました。コードモッドが利用可能です。
v13.0.0cookies が導入されました。