Next.js コードレビュー

概要

Next.js App Router コードをサーバーコンポーネント、クライアントコンポーネント、サーバーアクション、キャッシング戦略、本番環境対応基準のベストプラクティスに照らして評価します。重大度別に分類された実行可能な知見を具体的なコード例とともに生成します。アーキテクチャ分析は typescript-software-architect-review エージェントに委譲します。

使用タイミング

• マージ前に Next.js ページ、レイアウト、ルートセグメントをレビューする場合
• サーバーコンポーネント対クライアントコンポーネントの境界を検証する場合
• サーバーアクションのセキュリティと正確性をチェックする場合
• データ取得パターン（fetch、cache、revalidation）をレビューする場合
• キャッシング戦略（静的生成、ISR、動的レンダリング）を評価する場合
• ミドルウェア実装（認証、リダイレクト、リライト）を評価する場合
• API ルートハンドラーの適切なリクエスト/レスポンス処理をレビューする場合
• SEO のメタデータ設定を検証する場合
• loading、error、not-found ページの実装をチェックする場合
• 新しい Next.js 機能を実装した後、またはPages Router から移行した後

手順

1. スコープの特定: レビュー対象の Next.js ルートセグメントとコンポーネントを特定します。glob を使用して page.tsx、layout.tsx、loading.tsx、error.tsx、route.ts、middleware.ts ファイルを発見します。

2. コンポーネント境界の分析: サーバーコンポーネント/クライアントコンポーネントの適切な分離を検証します。'use client' が必要な場所にのみ配置され、コンポーネントツリーの可能な限り深い位置にあることを確認します。サーバーコンポーネントがクライアント専用モジュールをインポートしていないことを確認します。

3. データ取得のレビュー: fetch パターンを検証します。適切な cache と revalidate オプション、Promise.all による並列データ取得、リクエストウォーターフォール回避を確認します。サーバー側のデータ取得が機密データをクライアントに露出していないことを検証します。

4. キャッシング戦略の評価: 静的レンダリング対動的レンダリング決定をレビューします。静的生成のための generateStaticParams の使用、オンデマンド再検証のための revalidatePath/revalidateTag、API ルートの適切なキャッシュヘッダーをチェックします。

5. サーバーアクションの評価: フォームアクションをレビューします。適切な検証（クライアント側とサーバー側の両方）、エラーハンドリング、useOptimistic を使用した楽観的更新、セキュリティ（アクション認可なしで機密操作を露出しないことを確認）をレビューします。

6. ミドルウェアのチェック: ミドルウェアのリクエストマッチング、認証/認可ロジック、レスポンス修正、パフォーマンス影響をレビューします。必要なルートのみで実行されることを検証します。

7. メタデータと SEO のレビュー: generateMetadata 関数、Open Graph タグ、構造化データ、robots.txt、sitemap.xml 設定をチェックします。可変コンテンツを持つページで動的メタデータが適切に実装されていることを検証します。

8. 知見の検証: 最終化する前に、実際のコードコンテキストを確認して各問題を検証します。パターン違反が存在することを確認し、提案される修正がコードベースに適用可能であることを確認し、偽陽性を削除します。

9. レビューレポートの生成: 重大度別に分類された知見（重大、警告、提案）、肯定的な観察、優先度付きの推奨事項とコード例を含む構造化レポートを生成します。

例

例 1: サーバー/クライアントコンポーネント境界

// ❌ 悪い例: ボタンのみがインタラクティブな場合でもページ全体をクライアント化
'use client';

export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await fetch(`/api/products/${params.id}`);
  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <button onClick={() => addToCart(product.id)}>Add to Cart</button>
    </div>
  );
}

// ✅ 良い例: 独立したクライアントコンポーネントを持つサーバーコンポーネント
// app/products/[id]/page.tsx (Server Component)
import { AddToCartButton } from './add-to-cart-button';

export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const product = await getProduct(id);

  return (
    <div>
      <h1>{product.name}</h1>
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

// app/products/[id]/add-to-cart-button.tsx (Client Component)
'use client';

export function AddToCartButton({ productId }: { productId: string }) {
  return <button onClick={() => addToCart(productId)}>Add to Cart</button>;
}

例 2: データ取得パターン

// ❌ 悪い例: 順序立ったデータ取得によるウォーターフォール発生
export default async function DashboardPage() {
  const user = await getUser();
  const orders = await getOrders(user.id);
  const analytics = await getAnalytics(user.id);
  return <Dashboard user={user} orders={orders} analytics={analytics} />;
}

// ✅ 良い例: 適切な Suspense 境界を使用した並列データ取得
export default async function DashboardPage() {
  const user = await getUser();
  const [orders, analytics] = await Promise.all([
    getOrders(user.id),
    getAnalytics(user.id),
  ]);
  return <Dashboard user={user} orders={orders} analytics={analytics} />;
}

// ✅ さらに良い例: 独立したセクションに Suspense でストリーミング
export default async function DashboardPage() {
  const user = await getUser();
  return (
    <div>
      <UserHeader user={user} />
      <Suspense fallback={<OrdersSkeleton />}>
        <OrdersSection userId={user.id} />
      </Suspense>
      <Suspense fallback={<AnalyticsSkeleton />}>
        <AnalyticsSection userId={user.id} />
      </Suspense>
    </div>
  );
}

例 3: サーバーアクションセキュリティ

// ❌ 悪い例: 検証または認可なしのサーバーアクション
'use server';

export async function deleteUser(id: string) {
  await db.user.delete({ where: { id } });
}

// ✅ 良い例: 検証、認可、エラーハンドリング付きサーバーアクション
'use server';

import { z } from 'zod';
import { auth } from '@/lib/auth';
import { revalidatePath } from 'next/cache';

const deleteUserSchema = z.object({ id: z.string().uuid() });

export async function deleteUser(rawData: { id: string }) {
  const session = await auth();
  if (!session || session.user.role !== 'admin') {
    throw new Error('Unauthorized');
  }

  const { id } = deleteUserSchema.parse(rawData);
  await db.user.delete({ where: { id } });
  revalidatePath('/admin/users');
}

例 4: キャッシングと再検証

// ❌ 悪い例: キャッシュ制御なし、リクエストごとに取得
export default async function BlogPage() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
  return <PostList posts={posts} />;
}

// ✅ 良い例: 時間ベースの再検証で明示的にキャッシング
export default async function BlogPage() {
  const posts = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600, tags: ['blog-posts'] },
  }).then(r => r.json());
  return <PostList posts={posts} />;
}

// サーバーアクション内の再検証
'use server';
export async function publishPost(data: FormData) {
  await db.post.create({ data: parseFormData(data) });
  revalidateTag('blog-posts');
}

例 5: ミドルウェアレビュー

// ❌ 悪い例: ミドルウェアが静的アセットを含むすべてのルートで実行
import { NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  const session = request.cookies.get('session');
  if (!session) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
}
// config.matcher がない

// ✅ 良い例: 適切なマッチャーでスコープされたミドルウェア
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

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

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
};

レビュー出力フォーマット

すべてのコードレビュー知見を以下のように構造化します:

1. 要約

概括的な品質スコア（1-10）と主要な観察点を含む概要。

2. 重大問題（修正が必須）

セキュリティ脆弱性、データ露出、機能破損を引き起こす問題。

3. 警告（修正を推奨）

ベストプラクティス違反、パフォーマンス問題、保守性低下を引き起こす問題。

4. 提案（改善を検討）

コード組織、パフォーマンス、開発体験の改善。

5. 肯定的な観察

実装されたパターンと認識すべき良好なプラクティス。

6. 推奨事項

最も影響の大きい改善に対するコード例を含む優先度付きの次のステップ。

ベストプラクティス

• 'use client' の境界はツリーの可能な限り深い位置に保つ
• サーバーコンポーネントでデータを取得する — 初期データのクライアント側取得を避ける
• 並列データ取得（Promise.all）を使用してリクエストウォーターフォールを回避する
• すべてのルートセグメントに対して適切な loading、error、not-found の状態を実装する
• Zod または同等のライブラリを使用してすべてのサーバーアクション入力を検証する
• 時間ベースの再検証の代わりに revalidatePath/revalidateTag を使用する
• config.matcher で特定のルートにミドルウェアをスコープする
• 可変コンテンツを持つページに対して generateMetadata を実装する
• 既知のパラメータを持つ静的ページに対して generateStaticParams を使用する
• server-only パッケージを使用してサーバー専用コードをクライアントコンポーネントからインポートすることを避ける

制約と警告

• このスキルは Next.js App Router を対象としています — Pages Router パターンは大きく異なる場合があります
• プロジェクトの Next.js バージョンを尊重してください — いくつかの機能はバージョン固有です
• 明示的にリクエストされない限り、Pages Router から App Router への移行を提案しないでください
• キャッシング動作は開発環境と本番環境で異なります — 本番ビルドで検証してください
• サーバーアクションは機密操作を適切な認証チェックなしで露出してはいけません
• 高信頼度の問題に焦点を当ててください — スタイル選好の偽陽性を避けてください

参考資料

詳細なレビューチェックリストとパターンドキュメントについては、references/ ディレクトリを参照してください:

• references/app-router-patterns.md — App Router のベストプラクティスとパターン
• references/server-components.md — サーバーコンポーネント と クライアントコンポーネント境界ガイド
• references/performance.md — Next.js パフォーマンス最適化チェックリスト