Next.js(App Router)でCookieを扱うAPI
App RouterでCookieを扱うAPIは、次の3つです。
| API | 使える場所 | できること |
|---|---|---|
cookies()(next/headers) | Server Component / Server Function / Route Handler / proxy | 読み取り、書き込み(場所によって制限あり) |
request.cookies(NextRequest) | proxy / Route Handler | リクエストに入っているCookieの読み書き |
response.cookies(NextResponse) | proxy / Route Handler | レスポンスにSet-Cookieを付ける |
https://nextjsjp.org/docs/app/api-reference/functions/cookies
cookies() はNext.js 15から非同期になったので、await を付けて呼びます。
import { cookies } from 'next/headers'
const cookieStore = await cookies()
const token = cookieStore.get('token')?.value
使えるメソッドは get / getAll / has / set / delete / toString です。
Server Componentでは読むだけ
cookies().set と .delete が使えるのは、Server FunctionとRoute Handlerの中だけです。
Server Componentの描画中に呼ぶと、次のエラーになります。
Cookies can only be modified in a Server Action or Route Handler.
ストリーミングが始まった後ではレスポンスヘッダーを変えられない、というHTTPの制約によるものです。
実装では、書き込みを許可するかどうかをリクエストストアの phase で判定しています。
export function areCookiesMutableInCurrentPhase(requestStore: RequestStore) {
return requestStore.phase === 'action'
}
ページの描画用のストアは phase: 'render'(request-store.ts#L200)で作られるので、書き込みは拒否されます。Route Handler用のストアは phase: 'action'(request-store.ts#L221-L231)なので、書き込めます。
proxyでもcookies()は使える
Next.js 16で、middlewareはproxyに名前が変わりました。公式ドキュメントで cookies() を使える場所として挙げられているのはServer Component、Server Function、Route Handlerで、proxyは載っていません
それでも、実装上はproxyでも cookies() が使え、set も通ります。
proxyを実行する adapter.ts が、ハンドラーを呼ぶ前に createRequestStoreForAPI でリクエストストアを作っているためです。このストアはRoute Handlerと同じ phase: 'action' になります。
const onUpdateCookies = (cookies: Array<string>) => {
cookiesFromResponse = cookies
}
// ...
const requestStore = createRequestStoreForAPI(
request,
request.nextUrl,
implicitTags,
onUpdateCookies,
// ...
)
つまりproxyでは、Cookieを書く方法が cookies().set と response.cookies.set の2つあります。
問題は、この2つで新しい値が届く先が違うことです。
proxyで設定したCookieは、同じリクエストのどこに届くか
1回のリクエストの中で、proxyと、その後のページ描画やRoute Handlerは別々に動きます。ページやRoute Handlerの cookies() が読むのは、基本的にはブラウザが送ってきたCookieヘッダーです。
proxyが返すSet-Cookieは「ブラウザに保存して」という指示なので、ブラウザに届くのはレスポンスを返した後になります。
proxyで設定した値を同じリクエストの中で使えるようにするには、ルーターがproxyのレスポンスを受け取った時点で、後続の処理向けのリクエストに値を移す必要があります。
検証結果
ブラウザ側のCookieを token=old にしてリクエストを送り、proxyで token=new を設定したときに、それぞれの場所で token の値がどう見えるかを調べました。
| proxyでの設定方法 | ブラウザ | ページの cookies() | Route Handlerの cookies() | Route Handlerの request.cookies |
|---|---|---|---|---|
response.cookies.set | new | new | old | old |
cookies().set | new | old | old | old |
検証環境は Next.js 16.4.6 で、next build → next start(Node.jsランタイム)で動かし、curl でリクエストを送りました。
検証に使ったコード
// proxy.js
import { NextResponse } from 'next/server'
import { cookies } from 'next/headers'
export async function proxy(req) {
const mode = req.nextUrl.searchParams.get('m')
if (mode === 'fn') {
;(await cookies()).set('token', 'new')
return NextResponse.next()
}
const res = NextResponse.next()
res.cookies.set('token', 'new')
return res
}
// app/p/page.js
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'
export default async function Page() {
const c = await cookies()
return <div>{'PAGE:' + c.get('token')?.value}</div>
}
// app/api/a/route.js
import { cookies } from 'next/headers'
export const dynamic = 'force-dynamic'
export async function GET(req) {
const c = await cookies()
return Response.json({
cookiesFn: c.get('token')?.value,
reqCookies: req.cookies.get('token')?.value,
})
}
curl -s -D - -H 'Cookie: token=old' 'localhost:3000/api/a?m=fn'
curl -s -H 'Cookie: token=old' 'localhost:3000/p?m=fn'
response.cookies.setだけがページに届く理由
違いを生んでいるのは、x-middleware-set-cookie という内部用のヘッダーです。
response.cookies.setはページ向けのヘッダーも書く
NextResponse の cookies.set / delete を呼ぶと、Set-Cookieに加えて x-middleware-set-cookie ヘッダーも書き込まれます。
if (result instanceof ResponseCookies) {
headers.set(
'x-middleware-set-cookie',
result
.getAll()
.map((cookie) => stringifyCookie(cookie))
.join(',')
)
}
ルーターはproxyのレスポンスにこのヘッダーを見つけると、ブラウザへのレスポンスには載せず、後続の処理に渡すリクエストのヘッダーにだけ移します。
// for set-cookie, the header shouldn't be added to the response
// as it's only needed for the request to the middleware function.
if (key === 'x-middleware-set-cookie') {
req.headers[key] = value
continue
}
ページ描画のリクエストストアは、cookies を初めて読むときに mergeMiddlewareCookies を呼び、このヘッダーの値を元のCookieの上に書き込みます。そのため、ページの cookies() では new が見えます。
cookiesのgetter:request-store.ts#L295-L307mergeMiddlewareCookies:request-store.ts#L156-L181
cookies().setはブラウザ向けのSet-Cookieしか書かない
proxyの中で cookies().set を呼ぶと、変更内容は onUpdateCookies を通じて cookiesFromResponse に溜まります(request-cookies.ts#L116-L148)。最後に adapter.ts がそれを set-cookie ヘッダーに書き込みます。
if (response && cookiesFromResponse) {
response.headers.set('set-cookie', cookiesFromResponse)
}
x-middleware-set-cookie は書かれないので、ページ描画のCookieはブラウザから届いた old のままです。
これで困るのは、proxyで期限切れのアクセストークンを更新し、ページ側でそのトークンを使ってAPIを呼ぶ、という典型的なパターンです。cookies().set で更新すると、最初のリクエストだけ古いトークンでAPIを呼んでしまいます。
Route Handlerにはどちらの方法でも届かない
検証結果のとおり、Route Handlerでは response.cookies.set を使っても old のままでした。
mergeMiddlewareCookiesがHeadersオブジェクトを読めない
Route Handler用のリクエストストアは、NextRequest を渡して作られます(app-route/module.ts#L894-L901)。この場合、ヘッダーはWeb標準の Headers オブジェクトになります。
一方、mergeMiddlewareCookies は in 演算子と角括弧でヘッダーを読んでいます。これはNode.jsのプレーンなヘッダーオブジェクトにしか効かない読み方です。ソースにも、その旨のTODOコメントがあります。
// TODO: this only fires for `IncomingHttpHeaders`; `Headers` instances
// silently fall through (the `in` check and bracket access don't reach header
// values stored in internal slots). Confirm whether edge / Web `Headers`
// callers need this merge or already handle it elsewhere.
if (
'x-middleware-set-cookie' in headers &&
typeof headers['x-middleware-set-cookie'] === 'string'
) {
request.cookies のほうは、元々Cookieヘッダーを読むだけでマージ処理を通らないので、こちらも old です。
Route Handlerにも新しい値を届ける方法
proxyで request.cookies を書き換え、そのヘッダーを NextResponse.next({ request: { headers } }) で後続に渡します。ブラウザに保存させるために、response.cookies.set も合わせて行います。
// proxy.js
import { NextResponse } from 'next/server'
export async function proxy(req) {
// 後続の処理(ページ・Route Handler)向け
req.cookies.set('token', 'new')
const res = NextResponse.next({ request: { headers: req.headers } })
// ブラウザ向け
res.cookies.set('token', 'new')
return res
}
この方法で、ページ・Route Handlerの cookies()・Route Handlerの request.cookies のすべてで new が見えることを確認しました。
これは x-middleware-set-cookie とは別の仕組みです。NextResponse.next({ request }) に渡したヘッダーは x-middleware-request-* と x-middleware-override-headers に変換され(response.ts#L21-L28)、ルーターがリクエストヘッダーそのものを差し替えます(resolve-routes.ts#L668-L697)。Cookieヘッダー自体が token=new になるので、どこで読んでも新しい値になります。
cookies()とresponse.cookiesを混ぜるとSet-Cookieが消える
前の節で見た adapter.ts の処理は、append ではなく headers.set('set-cookie', ...) です。そのため、同じproxyの中で両方を使うと、response.cookies.set で付けたSet-Cookieが上書きされて消えます。
export async function proxy(req) {
;(await cookies()).set('a', '1')
const res = NextResponse.next()
res.cookies.set('b', '2') // ブラウザに届かない
return res
}
実際に試したところ、レスポンスに含まれていたのは set-cookie: a=1; Path=/ だけでした。
proxyの中では、どちらか一方に統一してください。
クライアント側でしか使わないなら、proxyでcookies()を使っても問題ない
proxyで設定したCookieを、ブラウザのJS(document.cookie など)でしか使わないなら、cookies().set でも問題ありません。どちらの方法でもブラウザにはSet-Cookieが届くからです。複数のCookieを設定した場合や、expires を付けた場合も、正しく届くことを確認しました。
set-cookie: a=1; Path=/; Expires=Tue, 01 Jan 2030 00:00:00 GMT
set-cookie: b=2; Path=/
ブラウザは、レスポンスヘッダーを受け取った時点でSet-Cookieを保存します。ページのJSが動くのはその後なので、document.cookie では最初のリクエストから新しい値が読めます。古い値が見えてしまうのは、サーバー側で動く cookies() だけです。
ただし、次の2点には注意してください。
- 同じproxyの中で
response.cookies.setと混ぜないこと httpOnly: trueを付けないこと(付けるとdocument.cookieから読めなくなる)
proxyで設定した値を、同じリクエストのサーバー側でも使うかどうかで、使う方法は次のように分かれます。
| 新しい値を使う場所 | proxyで使う方法 |
|---|---|
| ブラウザ(クライアントJS)だけ | cookies().set / response.cookies.set のどちらでもよい |
| ページ(Server Component)でも使う | response.cookies.set |
| Route Handlerでも使う | request.cookies.set + NextResponse.next({ request: { headers } }) + response.cookies.set |
本記事のコード引用・行番号はすべて Next.js v16.4.6 のソースに基づきます。内部実装に依存する挙動なので、バージョンアップで変わる可能性があります。