Route Handler
別名: ルートハンドラ / route.ts / route.js
Next.js の App Router で HTTP リクエストを直接受けるための仕組み。
app/ 配下に route.ts を置き、GET や POST という名前で関数を export すると、そのセグメントが API エンドポイントになる。
公開:
定義
Route Handler は、Next.js の App Router で HTTP リクエストを直接受け取るための仕組みである。app/ 配下のセグメントに route.ts(または route.js)を置き、GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS という名前の関数を export する。
そのセグメントの URL が、そのまま API エンドポイントになる。
Web 標準の Request を受け取り Response を返すので、フレームワーク独自のリクエスト型を覚える必要はない。
詳細
同じセグメントに page と route を同時に置くことはできない。
セグメントごとに、ページを描画するか、リクエストに応答するかのどちらかを選ぶ。
app/
api/
health/
route.ts ← GET /api/health
blog/
page.tsx ← /blog(ページ)// app/api/health/route.ts
export async function GET() {
return Response.json({ ok: true });
}書き出した関数名が許可されたメソッド名と一致しない場合、そのメソッドには応答しない。OPTIONS を自分で書かなかったときは、Next.js が既定の応答を組み立てる。
ランタイムは既定で Node.js だが、export const runtime = "edge" で Edge runtime に切り替えられる。
よくある誤解
- Route Handler は、
page.tsxから fetch される内部関数ではない。
独立した URL を持つエンドポイントで、外部からも呼べる。 - Route Handler は
middlewareの代わりにはならない。
middleware(16 以降はproxy)はリクエストが目的のルートへ届く前に挟まる層で、応答本体を組み立てる Route Handler とは役割が違う。
関連
ルーティング方式そのものは App Router の項で、サーバー側で動く描画単位は Server Component の項で説明している。
ブラウザから叩いて CORS で弾かれる症状は、Next.js の Route Handler で CORS エラーになる にまとめてある。