できない.dev

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 エラーになる にまとめてある。