Next.jsのRoute Handlerを型安全にするType Alias

Next.jsのApp Routerには特定のルートにカスタムリクエストハンドラーを作成できるRoute Handlerがあります。

Route Handlerは非常に強力ですが、デフォルトではResponseの型情報を参照できないという小さな欠点があります。この記事では、Type Aliasを活用してレスポンスの型情報を推論する方法をご紹介します。

Next.jsのRoute Handlerについて

型推論のソリューションに入る前に、Route Handlerとは何か、そしてなぜそれほど有用なのかを簡単に見てみましょう。

Next.jsのRoute Handlerは、アプリケーションの特定のルートに対してAPIエンドポイントやカスタムサーバーサイドロジックを作成する方法を提供します。これらはWeb RequestとResponse APIを使用しており、他のサーバーサイドJavaScriptフレームワークを使用したことがある開発者にとって馴染みやすいものです。

以下はRoute Handlerの簡単な例です：

export async function GET(request: Request) {
  return new Response('Hello, Next.js!')
}

このハンドラーは、GETリクエストに対して単純に "Hello, Next.js!" というメッセージで応答します。

型情報の課題

Route Handlerは強力ですが、デフォルトではResponseの型情報を簡単に参照できないという制限があります。これにより、型関連のエラーが発生する可能性があり、アプリケーション全体で型の安全性を確保することが難しくなります。

この課題に対して、ZodやValibotなどのスキーマバリデーションライブラリを使ってレスポンスのスキーマを定義する方法がありますが、今回は別のアプローチとして型推論を使用する方法を紹介します。

その後、型推論を使った場合の強みとスキーマバリデーションライブラリを使った場合の強みについて比較します。

Route Handlerの戻り値の型を推論するType Aliasの導入

Route Handlerの戻り値の型を推論するType Aliasは、以下のような定義になります。

import { NextResponse } from 'next/server'

type InferNextResponseType<T> = T extends (...args: any[]) => Promise<NextResponse<infer U>> ? U : never

InferNextResponseType<typeof GET>のようにすることで、GETハンドラーのレスポンス型を推論することができます。

import { NextResponse } from 'next/server'
import type { InferNextResponseType } from '@/helpers/api'

export async function GET() {
  return NextResponse.json({ message: 'Hello, World!' })
}

type ResponseType = InferNextResponseType<typeof GET>
//^? { message: string }

ここで何が起こっているか詳しく見てみましょう：

条件付き型を使用してRoute Handler関数からレスポンスの型を推論するInferNextResponseType<T>というType Aliaseを定義します。
このType Aliasは、TがPromise<NextResponse<infer U>>を返す関数を拡張しているかどうかをチェックします。ここでUはレスポンス本体の推論された型です。
条件が真の場合、U（推論された型）を返し、そうでない場合はneverを返します。
その後、このType Aliasをtypeof GETと共に使用して、GETハンドラーのレスポンス型を推論します。

SWRを使用したクライアントの実装例

このType Aliasを利用してクライアントの実装がどのようになるかを見てみましょう。今回はNext.jsと組み合わせて使うことが比較的多いSWRを使いますが、他のライブラリでもfetchでも同様の方法で型推論を行うことができます。

型推論しない場合

Type Aliasを利用せず、型推論をしない場合、SWRを使った実装は以下のようになります。

import useSWR from 'swr'

const fetcher = (url: string) => fetch(url).then(res => res.json())

export default function Page() {
  const { data, error } = useSWR('/api/hello', fetcher)

  if (error) return <div>読み込みに失敗しました</div>
  if (!data) return <div>読み込み中...</div>

  return <div>{data.message}</div>
}

この場合、dataの型はanyなので、data.messageの型チェックや自動補完が得られません。

型推論した場合

では、InferNextResponseTypeを使用して型を推論してみましょう。

import useSWR from 'swr'
import type { InferNextResponseType } from '@/helper/api'
import type { GET } from '@/app/api/hello/route'

const fetcher = (url: string) => fetch(url).then(res => res.json())

export default function Page() {
  const { data, error } = useSWR<InferNextResponseType<typeof GET>>('/api/hello', fetcher)

  if (error) return <div>読み込みに失敗しました</div>
  if (!data) return <div>読み込み中...</div>

  return <div>{data.message}</div>
}