ルートハンドラー

ルートハンドラー

ルートハンドラーを使用すると、Web Request および Response API を使用して、指定されたルートのカスタムリクエストハンドラーを作成できます。

注目情報：ルートハンドラーは app ディレクトリ内でのみ利用可能です。これは pages ディレクトリ内の API Routes に相当するため、API Routes とルートハンドラーを一緒に使用する必要はありません。

規約

ルートハンドラーは、app ディレクトリ内の route.js|ts ファイル に定義されます。

export async function GET(request: Request) {}

ルートハンドラーは、page.js および layout.js と同様に、app ディレクトリ内のどこにでもネストできます。ただし、page.js と同じルートセグメントレベルに route.js ファイルを配置することはできません。

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

以下の HTTPメソッド がサポートされています：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。サポートされていないメソッドが呼び出された場合、Next.js は 405 Method Not Allowed レスポンスを返します。

拡張された NextRequest および NextResponse API

ネイティブの Request および Response API をサポートするだけでなく、Next.js は高度なユースケースのために便利なヘルパーを提供する NextRequest および NextResponse で拡張しています。

キャッシュ

ルートハンドラーはデフォルトでキャッシュされません。ただし、GET メソッドのキャッシュをオプトインすることができます。その他のサポートされているHTTPメソッドはキャッシュされません。GET メソッドをキャッシュするには、ルートハンドラーファイルに export const dynamic = 'force-static' のような ルート設定オプション を使用します。

export const dynamic = 'force-static'
 
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 })
}

注目情報：その他のサポートされているHTTPメソッドは、同じファイル内でキャッシュされる GET メソッドと並んで配置されていても、キャッシュされません。

特別なルートハンドラー

sitemap.ts、opengraph-image.tsx、icon.tsx などの特別なルートハンドラー、およびその他の メタデータファイル は、動的APIまたは動的な設定オプションを使用しない限り、デフォルトで静的です。

ルート解決

route は、最も基本的なルーティングプリミティブと考えることができます。

• これらは、page とは異なり、レイアウトやクライアントサイドナビゲーションには参加しません。
• page.js と同じルートに route.js ファイルを配置することはできません。

各 route.js または page.js ファイルは、そのルートのすべてのHTTP動詞を引き継ぎます。

export default function Page() {
  return <h1>Hello, Next.js!</h1>
}
 
// Conflict
// `app/route.ts`
export async function POST(request: Request) {}

ルートハンドラーが フロントエンドアプリケーションを補完する方法 についてさらに読むか、ルートハンドラーの APIリファレンス を参照してください。

ルートコンテキストヘルパー

TypeScript では、ルートハンドラーの context パラメータを、グローバルで利用可能な RouteContext ヘルパーで型付けできます。

import type { NextRequest } from 'next/server'
 
export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}

知っておくと良いこと

• 型は next dev、next build、または next typegen の実行中に生成されます。