Route Handlers
Route Handlers を使うと、Web Request と Response API を使って、指定したルートのカスタムリクエストハンドラを作成できます。
Good to know: ルートハンドラは
app
ディレクトリ内でのみ利用可能です。これらはpages
ディレクトリ内の API Routes に相当します。つまり、API Routes と Route Handlers を一緒に使う必要はありません。
規約
ルートハンドラはapp
ディレクトリ内のroute.js|ts
ファイルで定義されます。
export const dynamic = 'force-dynamic' // defaults to auto
export async function GET(request: Request) {}
ルートハンドラは page.js
や layout.js
と同じように app
ディレクトリの中に入れ子にできます。しかし、page.js
と同じルート Segment レベルに route.js
ファイルを置くことはできません。
サポートされる HTTP メソッド
以下のHTTP メソッドがサポートされている: GET
、POST
、PUT
、PATCH
、DELETE
、HEAD
および OPTIONS
です。サポートされていないメソッドが呼び出された場合、Next.js は 405 Method Not Allowed
応答を返します。
拡張 NextRequest
と NextResponse
API
ネイティブのRequestとResponseをサポートしています。Next.js はこれらを次のように拡張します。
NextRequest
とNextResponse
で拡張し、高度なユースケースのための便利なヘルパーを提供します。
Behavior
キャッシング
Response
オブジェクトで GET
メソッ ドを使用する場合、Route ハンドラはデフォルトでキャッシュされます。
export async function GET() {
const res = await fetch('https://data.mongodb-api.com/...', {
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY,
},
})
const data = await res.json()
return Response.json({ data })
}
TypeScript Warning:
Response.json()
は TypeScript 5.2 以降でのみ有効です。それ以下のバージョンの TypeScript を使用している場合は、代わりに型付きレスポンスのNextResponse.json()
を使用することができます。
キャッシュのオプトアウト
キャッシュ無効にするには以下の方法があります:
GET
メソッドでRequest
オブジェクトを使用する。- その他の HTTP メソッドを使用する。
cookies
やheaders
などの Dynamic Functions を使用する。- セグメント設定オプション で手動で動的モードを指定する。
例えば
export async function GET(request: Request) {
const { searchParams } = new URL(request.url)
const id = searchParams.get('id')
const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY,
},
})
const product = await res.json()
return Response.json({ product })
}
同様に、POST
メソッドは Route Handler を動的に評価します。
export async function POST() {
const res = await fetch('https://data.mongodb-api.com/...', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'API-Key': process.env.DATA_API_KEY,
},
body: JSON.stringify({ time: new Date().toISOString() }),
})
const data = await res.json()
return Response.json(data)
}
Good to know: API Routes のように、Route Handlers はフォームの送信を処理するようなケースに使うことができます。React と深く統合された、Server Actionsとミューテーションを処理するための新しい抽象化に取り組んでいます。
Route 解決
ルート
は最下層のルーティングプリミティブと考えることができます。
- それらは
page
のようなレイアウトやクライアントサイドのナビゲーションには 参加しません。 page.js
と同じルートにroute.js
ファイルを置くことはできません。
Page | Route | Result |
---|---|---|
app/page.js | app/route.js | Conflict |
app/page.js | app/api/route.js | Valid |
app/[user]/page.js | app/api/route.js | Valid |
各 route.js
または page.js
ファイルは、そのルートのすべての HTTP verbs を引き継ぎます。
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
// ❌ Conflict
// `app/route.js`
export async function POST(request) {}
Examples
次の例では、Route ハンドラを他の Next.js API や機能と組み合わせる方法を示します。
静的データの再検証
静的データの再検証フェッチは、next.revalidate
オプションを使って行うことができます:
export async function GET() {
const res = await fetch('https://data.mongodb-api.com/...', {
next: { revalidate: 60 }, // Revalidate every 60 seconds
})
const data = await res.json()
return Response.json(data)
}