Frontend Academy · レッスン

Next.jsのAPI RoutesとMiddleware

api/ディレクトリにサーバーレスAPIエンドポイントを作成し、Route Handlersでリクエストを処理して、認証やリダイレクト用のエッジMiddlewareを実行します。

「Next.jsのAPI RoutesとMiddleware」はCoddyKit上の無料Frontend Academyレッスンです。これはレッスン4/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはFrontend Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Frontend Academyコースには全4レッスンが含まれています。

APIルートを使う理由

Next.jsはアプリと一緒にサーバーを提供するため、別のNodeプロジェクトを用意せずに、ページと同じ場所にバックエンドのエンドポイントを書けます。プロキシ、フォーム送信、Webhook、小規模なAPIに適しています。

Pages RouterのAPIルート

pages/api/内のファイルでは、Express形式の（req, res）を受け取るデフォルト関数をエクスポートします。

// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method === 'GET') {
    const users = await db.users.findMany();
    return res.json(users);
  }
  if (req.method === 'POST') {
    const user = await db.users.create({ data: req.body });
    return res.status(201).json(user);
  }
  return res.status(405).end();
}

App RouterのRoute Handlers

App Routerでは、Web標準のRequest/Response APIを使用します。各HTTPメソッドを名前付きエクスポートとして定義します。

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

export async function GET() {
  const users = await db.users.findMany();
  return NextResponse.json(users);
}

export async function POST(request: Request) {
  const body = await request.json();
  const user = await db.users.create({ data: body });
  return NextResponse.json(user, { status: 201 });
}

動的APIルート

動的セグメントも同じように機能します。app/api/users/[id]/route.tsは/api/users/123に一致します。

// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
  const user = await db.users.findUnique({ where: { id: params.id }});
  if (!user) return new Response('Not Found', { status: 404 });
  return Response.json(user);
}

Cookieとヘッダーの読み取り

App Routerでは、next/headersのヘルパーを使用します（リクエスト単位で利用できます）。

import { cookies, headers } from 'next/headers';

export async function GET() {
  const token = cookies().get('token')?.value;
  const userAgent = headers().get('user-agent');
  // ...
}

レスポンスのストリーミング

Route handlersはストリーミングレスポンスを返せます。AIチャットの補完や大きなファイルの生成に便利です。

export async function GET() {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      for (let i = 0; i < 5; i++) {
        controller.enqueue(encoder.encode(`chunk ${i}\n`));
        await new Promise(r => setTimeout(r, 500));
      }
      controller.close();
    }
  });
  return new Response(stream);
}

Middleware — ルートの前に実行

プロジェクトルートのmiddleware.tsは、リクエストがページやAPIルートに到達する前に実行されます。認証チェック、リダイレクト、ヘッダーの書き換え、A/Bテストに使用します。

// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('token');
  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
  return NextResponse.next();
}

Middleware Matcher

matcher設定を使うと、Middlewareを実行するパスを制限できます。

export const config = {
  matcher: [
    '/dashboard/:path*',
    '/api/:path*',
    '/((?!_next/static|_next/image|favicon.ico).*)'
  ]
};

Middlewareのランタイム

MiddlewareはデフォルトでEdge Runtime上で実行されます。これは軽量なV8アイソレートであり、完全なNodeではありません。利用できるAPIは限られており、fsのようなNodeモジュールやネイティブ依存関係は使用できません。

Middlewareを使った認証パターン

よくある構成は、MiddlewareでJWTを検証し、存在しないか無効な場合はログインへリダイレクトし、デコードしたユーザー情報を後続のルートが読み取れるリクエストヘッダーに付加する方法です。

import jwt from 'jsonwebtoken';

export function middleware(req: NextRequest) {
  const token = req.cookies.get('token')?.value;
  if (!token) return NextResponse.redirect(new URL('/login', req.url));
  try {
    const decoded = jwt.verify(token, process.env.SECRET!);
    const res = NextResponse.next();
    res.headers.set('x-user-id', String(decoded.sub));
    return res;
  } catch {
    return NextResponse.redirect(new URL('/login', req.url));
  }
}

Middlewareでのレート制限

MiddlewareとKVストア（Upstash、Vercel KV）を組み合わせると、APIのロジックに到達する前に、IPごとのレート制限を適用できます。

APIルートを使わない場合

独立したマイクロサービスや共有APIには、実際のバックエンド（Hono、Express、NestJS）をデプロイしてください。Next.jsのAPIルートは、プロキシ、Webhook、アプリ固有のエンドポイントに適していますが、他のクライアント向けの公開APIを提供する用途には適していません。

クイックチェック

Next.jsのMiddlewareはどこで実行され、最も一般的な用途は何ですか？

振り返り：APIルートとMiddleware

Pages Router：pages/apiでreq/resを使用します。App Router：app/api/.../route.tsで、Request/Responseを使い、メソッドのエクスポート（GET/POSTなど）を定義します。Cookieやヘッダーはnext/headersで読み取ります。ReadableStreamでレスポンスをストリーミングできます。middleware.tsはルートの前にEdge上で実行され、認証、リダイレクト、ヘッダー処理に使用します。Matcher設定で対象パスを制限できます。公開APIには実際のバックエンドを使用してください。

よくある質問

「Next.jsのAPI RoutesとMiddleware」レッスンは無料ですか？

はい。「Next.jsのAPI RoutesとMiddleware」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Frontend Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Frontend Academyコースには全4レッスンが含まれています。

「Next.jsのAPI RoutesとMiddleware」で何を学びますか？

api/ディレクトリにサーバーレスAPIエンドポイントを作成し、Route Handlersでリクエストを処理して、認証やリダイレクト用のエッジMiddlewareを実行します。ブラウザで直接実行するハンズオンコードでFrontend Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Frontend Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのFrontend Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン4/4です。

「Next.jsのAPI RoutesとMiddleware」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このFrontend Academyレッスンでコードを書いて実行できますか？

はい。すべてのFrontend Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← Frontend Academyに戻る