Route Handlers

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

補足：Route Handlersはappディレクトリ内でのみ利用可能です。これはpagesディレクトリ内のAPI Routesと同等であり、API RoutesとRoute Handlersを一緒に使用する必要はありません。

規則

Route Handlersはappディレクトリ内のroute.js|tsファイルで定義されます：

app/api/route.ts

TypeScript

export async function GET(request: Request) {}

Route Handlersは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

Next.jsは、ネイティブなRequest及びResponse APIに加えて、NextRequest及びNextResponseで拡張し、高度なユースケースに便利なヘルパーを提供します。

Route Handlersはデフォルトではキャッシュされません。ただし、GETメソッドに対してキャッシングをオプトインできます。他のサポートされているHTTPメソッドはキャッシュされません。GETメソッドをキャッシュするには、Route Handlerファイル内でexport const dynamic = 'force-static'などのルート設定オプションを使用します。

app/items/route.ts

TypeScript

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メソッドと一緒に配置されていても、キャッシュされません。

特殊なRoute Handlers

sitemap.ts、opengraph-image.tsx及びicon.tsxなどの特殊なRoute Handlersや、その他のメタデータファイルは、Dynamic APIまたはダイナミック設定オプションを使用しない限り、デフォルトでは静的のままです。

ルート解決

routeをルーティングの最下位のプリミティブと見なすことができます。

pageのようにレイアウトやクライアント側ナビゲーションに参加しません。
同じルートにroute.jsファイルとpage.jsファイルが存在することはできません。

Page	Route	Result
`app/page.js`	`app/route.js`	競合
`app/page.js`	`app/api/route.js`	有効
`app/[user]/page.js`	`app/api/route.js`	有効

各route.jsまたはpage.jsファイルは、そのルートのすべてのHTTP動詞を制御します。

app/page.ts

TypeScript

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

Route Handlersがフロントエンドアプリケーションを補完する方法の詳細や、Route Handlers API Referenceについて確認できます。

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

TypeScriptでは、グローバルに利用可能なRouteContextヘルパーを使用して、Route Handlersのcontextパラメータに型を付けることができます：

app/users/[id]/route.ts

TypeScript

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の実行時に生成されます。

Route Handlers

API Reference

フロントエンド用バックエンド

route.js