cookies
cookies
は 非同期 関数で、サーバーコンポーネントで HTTP 受信リクエストのクッキーを読み取り、サーバーアクションまたはルートハンドラーで送信リクエストのクッキーを読み書きすることができます。
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 | 文字列 | クッキーに保存する値を指定します。 |
expires | Date | クッキーが期限切れになる正確な日時を定義します。 |
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でもまだ同期的にアクセスできますが、この動作は将来的に非推奨となります。
- バージョン14以前では、
cookies
は 動的API であり、返される値は事前に知ることができません。レイアウトやページでこれを使用すると、ルートは 動的レンダリング にオプトインされます。.delete
メソッドを呼び出せるのは以下の場合のみです:- HTTPではストリーミングが開始された後にクッキーを設定することはできないため、サーバーアクションまたはルートハンドラーで
.set
を使用する必要があります。
サーバーコンポーネントでのクッキーの動作について
サーバーコンポーネントでクッキーを扱う際には、クッキーが基本的にクライアント側のストレージメカニズムであることを理解しておくことが重要です:
- クッキーの読み取りはサーバーコンポーネントで機能します。これは、クライアントのブラウザがHTTPリクエストヘッダーでサーバーに送信するクッキーデータにアクセスしているためです。
- クッキーの設定は、ルートハンドラーやサーバーアクションを使用している場合でも、サーバーコンポーネントで直接行うことはできません。これは、クッキーが実際にはサーバーではなくブラウザによって保存されるためです。
サーバーは(Set-Cookie
ヘッダーを介して)ブラウザにクッキーを保存するよう指示を送ることしかできません - 実際の保存はクライアント側で行われます。これが、状態を変更するクッキー操作(.set
、.delete
、.clear
)が、レスポンスヘッダーを適切に設定できるルートハンドラーまたはサーバーアクションで実行される必要がある理由です。
例
クッキーの取得
(await cookies()).get('name')
メソッドを使用して単一のクッキーを取得できます:
import { cookies } from 'next/headers'
export default async function Page() {
const cookieStore = await cookies()
const theme = cookieStore.get('theme')
return '...'
}
すべてのクッキーの取得
(await cookies()).getAll()
メソッドを使用して、一致する名前を持つすべてのクッキーを取得できます。name
が指定されていない場合は、利用可能なすべてのクッキーを返します。
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
オブジェクトはオプションです。
'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)
メソッドを使用して、クッキーが存在するかどうかを確認できます:
import { cookies } from 'next/headers'
export default async function Page() {
const cookieStore = await cookies()
const hasCookie = cookieStore.has('theme')
return '...'
}
クッキーの削除
クッキーを削除するには3つの方法があります。
delete()
メソッドを使用する:
'use server'
import { cookies } from 'next/headers'
export async function delete(data) {
(await cookies()).delete('name')
}
同じ名前で空の値を持つ新しいクッキーを設定する:
'use server'
import { cookies } from 'next/headers'
export async function delete(data) {
(await cookies()).set('name', '')
}
maxAge
を 0 に設定すると、クッキーは直ちに期限切れになります。maxAge
は秒単位の値を受け取ります。
'use server'
import { cookies } from 'next/headers'
export async function delete(data) {
(await cookies()).set('name', 'value', { maxAge: 0 })
}
バージョン履歴
バージョン | 変更点 |
---|---|
v15.0.0-RC | cookies は非同期関数になりました。コードモッドが利用可能です。 |
v13.0.0 | cookies が導入されました。 |