優先度: P0 (最重要)
実装ガイドライン
ルーティングアーキテクチャ
- 構造:
app/ ディレクトリを使用します。app/dashboard/layout.tsx で {children} を返すようにルートを定義します。共有UIは自動的に app/layout.tsx 内にネストされます。loading.tsx、error.tsx、not-found.tsx で状態を処理します。
- セグメント: ルートグループ(括弧
(auth))を使用して機能を整理し、URL パスから 除外 します。動的ルート(括弧 [slug])を使用し、generateStaticParams で静的パスを定義します。
- 特殊なルーティング: パラレルルート(
@modal)は、スロットを親レイアウトに追加し、default.tsx フォールバックを提供して使用します。インターセプティングルート((.)route)は、ダッシュボードなどの高度なレイアウトに使用します。
データと関数
- Next.js 15+ 非同期: 常に
params: Promise、searchParams、cookies()、headers() を await します。
- セキュリティ: エッジサイドの認証とリダイレクトには
middleware.ts を使用します。すべての ルートハンドラー (route.ts) が適切な認証チェックで保護されていることを確認します。
- RSC: デフォルトで React Server Components (RSC) を使用します。
'use client' は対話性(フック/イベント)のためにリーフノードでのみ使用します。
- エラーバウンダリ:
app/dashboard/loading.tsx を作成して、ルートを自動的に Suspense バウンダリ でラップします。error.tsx では 'use client' を使用し、reset: () => void 関数を提供します。
const cookieStore = await cookies();
const theme = cookieStore.get('theme');
ファイル規約
- page.tsx: ルートのUI。
- layout.tsx: 子要素をラップする共有UI。ナビゲーション間で永続化されます。
- loading.tsx: ローディング状態の Suspense バウンダリ。
- error.tsx: エラーバウンダリ(クライアントコンポーネントである必要があります)。
- route.ts: サーバーサイドのAPIエンドポイント。
構造パターン
- ルートグループ: 括弧
(auth) を使用して、URL パスに影響を与えずに整理します。
- プライベートフォルダ: アンダースコア
_lib を使用してルーティングから除外します。
- 動的ルート: 括弧
[slug] または [...slug](キャッチオール)を使用します。
ベストプラクティス
- RSC バウンダリ: クライアントコンポーネントに渡される props がシリアライズ可能であることを確認します。RSC Boundaries & Serialization を参照してください。
- パラレルルート (
@folder): 同じレイアウト内で複数のページをレンダリングします。フォールバックには default.tsx を使用します。
- インターセプティングルート (
(..)folder): 現在のレイアウトコンテキスト内でルートをロードします。
- コロケーション: コンポーネントファイル、スタイル、テストをルートフォルダ内に配置します。
- レイアウト:
<html> タグと <body> タグにはルートレイアウト (app/layout.tsx) を使用します。
- セルフホスティング標準
アンチパターン
- 未 await の非同期 API は避ける:
params、cookies()、headers() は Next.js 15+ では Promises です。常に await します。
- ツリーのルートに
'use client' を置かない: リーフに配置し、レイアウトとページはサーバーコンポーネントとして維持します。
- ネストされたレイアウトに
<html>/<body> を置かない: app/layout.tsx(ルートレイアウト)のみがこれらを含む必要があります。
error.tsx の欠落を避ける: すべてのルートセグメントにはクライアントコンポーネントのエラーバウンダリが必要です。