【Next.js】Route Handlers

Route Handlers って

役割：Route Handlers は、API のエンドポイントを作る方法。

HTTPリクエストに対してどうレスポンスするかを直接扱える仕組み

作成場所

appディレクトリの配下でroute.ts もしくは route.jsというファイルを作成する。

app/api/hello/route.ts

route.ts中身ざっくり

HTTPメソッドごとに関数をエクスポートする。

// app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ message: 'Hello world' });
}

// /api/hello に GET リクエストすると { "message": "Hello world" } が返る。

サポートされるHTTPメソッド

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

もし未定義のメソッドで呼ばれた場合は、Next.js が自動で 405 Method Not Allowed を返す。

RequestとResponse

• 標準の Web API と同じ Request / Response が使える。

• Next.js 独自の拡張版：
  • NextRequest URL パラメータやクッキーを簡単に扱える。
  • NextResponse
    • JSON を返す NextResponse.json()
    • リダイレクト NextResponse.redirect()
    • Rewrites など

NextResponseとは

NextResponse はNext.js（App Router）の サーバーコンポーネントやAPI Routeでレスポンスを作るためのオブジェクト 。

通常の Node.js や Express だと res.json(...) を使うが、Next.js の App Router では Web標準の Response API に近い形でレスポンスを扱う。

NextResponseの役割

NextResponse.json(data) を呼ぶと：

• Content-Type: application/json ヘッダーを自動で付与
• data を JSON 文字列に変換して返す
• 型安全（TypeScript で data の型を保持）

キャッシュ（Caching）

Route Handlers は「どうキャッシュされるか」が重要ポイント。

• デフォルトでは、Route Handlers はキャッシュされない
• GET メソッドについてはキャッシュを有効にすることが可能
• 下記を設定することで静的キャッシュを強制できる

export const dynamic = 'force-static'; 

• GET 以外のメソッド（POST, PUT など）はキャッシュされない
• 同じファイルで GET をキャッシュ設定してあっても、他のメソッドはキャッシュ対象外

特別な Route Handlers（特殊なルートハンドラ）

• sitemap.ts、opengraph-image.tsx、icon.tsx などのメタデータ系ファイルも、特別扱いされる Route Handlers の一種。これらはデフォルトで静的（static）とみなされ、動的 API 機能を使わない限り常に静的になる。 

ページとの違い

• page.tsx = ユーザーに HTML を返す（UI）
• route.ts = API エンドポイント（データ提供）

つまり、同じ階層に page.tsx と route.ts は置けない。

c.sakyou