Next.js App Router 完全ガイド：アーキテクチャ、パターン、エンタープライズのベストプラクティス (2026年)

// app/[locale]/products/page.tsx - サーバーコンポーネント
import { Suspense } from 'react';
import { db } from '@/lib/db';
import { ProductCard } from '@/components/ProductCard';
import { SearchFilter } from '@/components/SearchFilter'; // クライアントコンポーネント

export default async function ProductsPage({
  searchParams,
}: {
  searchParams: { q?: string; category?: string };
}) {
  // 内部的なHTTPオーバーヘッドなしで、サーバー上で直接安全にデータベースクエリを実行
  const products = await db.product.findMany({
    where: {
      category: searchParams.category,
      title: { contains: searchParams.q, mode: 'insensitive' },
    },
  });

  return (
    <div className="space-y-6">
      {/* 入力とフィルタリングのためのインタラクティブなクライアントコンポーネント */}
      <SearchFilter />
      
      {/* 非インタラクティブなサーバーレンダリングカード */}
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {products.map((item) => (
          <ProductCard key={item.id} product={item} />
        ))}
      </div>
    </div>
  );
}

app/
├── [locale]/                      # 動的ロケールセグメント (i18n)
│   ├── (marketing)/               # ルートグループ: 未認証マーケティングシェル
│   │   ├── about/
│   │   │   └── page.tsx
│   │   ├── layout.tsx             # マーケティング用ナビゲーションとフッター
│   │   └── page.tsx               # ランディングページ
│   ├── (dashboard)/               # ルートグループ: 認証済みダッシュボードシェル
│   │   ├── settings/
│   │   │   └── page.tsx
│   │   ├── layout.tsx             # サイドバーと認証済みセッションのレイアウト
│   │   └── page.tsx               # アナリティクス概要
│   ├── blog/
│   │   ├── [slug]/
│   │   │   ├── opengraph-image.tsx # 動的OG画像ジェネレーター
│   │   │   └── page.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── api/
│   │   └── webhooks/
│   │       └── stripe/
│   │           └── route.ts       # Edge / サーバーレス ルートハンドラー
│   ├── layout.tsx                 # ルートのHTML/Bodyレイアウトとテーマプロバイダー
│   ├── not-found.tsx              # ローカライズされた404ハンドラー
│   └── error.tsx                  # ローカライズされたエラーバウンダリ

// lib/data/articles.ts
export async function getFeaturedArticles() {
  const res = await fetch('https://api.example.com/articles?featured=true', {
    next: {
      tags: ['articles', 'articles-featured'],
      revalidate: 3600, // バックグラウンドでの再検証フォールバック (1時間)
    },
  });

  if (!res.ok) throw new Error('Failed to fetch articles');
  return res.json();
}

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');
  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ message: 'Invalid token' }, { status: 401 });
  }

  const tag = request.nextUrl.searchParams.get('tag');
  if (tag) {
    revalidateTag(tag);
    return NextResponse.json({ revalidated: true, tag, now: Date.now() });
  }

  return NextResponse.json({ message: 'Missing tag parameter' }, { status: 400 });
}

// app/[locale]/newsletter/NewsletterForm.tsx
'use client';

import { useActionState } from 'react';
import { subscribeNewsletter } from '@/actions/newsletter';

interface ActionState {
  success?: boolean;
  message?: string;
  errors?: Record<string, string[]>;
}

const initialState: ActionState = {};

export function NewsletterForm() {
  const [state, formAction, isPending] = useActionState(subscribeNewsletter, initialState);

  return (
    <form action={formAction} className="space-y-4 max-w-md">
      <div>
        <label htmlFor="email" className="block text-sm font-medium mb-1">
          Work Email
        </label>
        <input
          id="email"
          name="email"
          type="email"
          required
          placeholder="engineer@company.com"
          className="w-full px-4 py-2 border rounded-lg dark:bg-gray-900 dark:border-gray-700"
        />
        {state.errors?.email && (
          <p className="text-red-500 text-xs mt-1">{state.errors.email[0]}</p>
        )}
      </div>

      <button
        type="submit"
        disabled={isPending}
        className="px-5 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded-lg disabled:opacity-50"
      >
        {isPending ? 'Subscribing...' : 'Subscribe'}
      </button>

      {state.message && (
        <p className={`text-sm ${state.success ? 'text-green-600' : 'text-red-500'}`}>
          {state.message}
        </p>
      )}
    </form>
  );
}

[Vercel Lambda 1] -+
[Vercel Lambda 2] -+-> [Pooler: PgBouncer]
[Vercel Lambda N] -+         |
                             v
                    [PostgreSQL Primary]

// lib/db.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const db =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
  });

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = db;

// app/[locale]/dashboard/page.tsx
import { Suspense } from 'react';
import { UserGreeting } from './UserGreeting';
import { StaticMarketingBanner } from './StaticMarketingBanner';
import { MetricsSkeleton } from './MetricsSkeleton';

export const experimental_ppr = true;

export default function DashboardPage() {
  return (
    <div className="space-y-6">
      {/* 1. 静的シェル: エッジのCDNキャッシュから即座に配信される */}
      <StaticMarketingBanner />

      {/* 2. 動的ホール: データ解決時にHTTPチャンキングを通じてストリーミングされる */}
      <Suspense fallback={<MetricsSkeleton />}>
        <UserGreeting />
      </Suspense>
    </div>
  );
}