Next.js Best Practice

ディレクトリ構造

src/
├── app/ # Next.js App Router - ルーティングとページ
├── components/
│ ├── ui/      # Shadcn/ui コンポーネント - 再利用可能な UI プリミティブ
│ └── layouts/ # 一貫したページ構造のためのレイアウトコンポーネント
├── hooks/     # 共有ロジックのためのカスタム React フック
├── types/     # TypeScript 型定義
├── lib/
│ ├── constants/ # アプリケーション定数と設定
│ ├── utils/     # ユーティリティ関数とヘルパー
│ ├── actions/   # Server Actions（サーバーサイドのミューテーション）
│ └── services/  # ドメインサービス（ビジネスロジック、外部API呼び出し等）
└── tests/
├── unit/        # 個別の関数/コンポーネントのユニットテスト
├── integration/ # コンポーネント相互作用の統合テスト
└── e2e/         # 完全なユーザーフローのエンドツーエンドテスト

ファイル命名規則

• Pages: page.tsx – Next.js App Router のページコンポーネント
• Layouts: layout.tsx – ルートグループの共有レイアウトコンポーネント
• Loading: loading.tsx – ルートセグメントのローディング UI
• Errors: error.tsx – ルートセグメントのエラー境界コンポーネント
• APIs: route.ts – サーバーエンドポイントの API ルートハンドラー

コンポーネント設計原則

• Server Components (デフォルト): データフェッチ、SEO 最適化、静的コンテンツのレンダリングに使用
• Client Components (必要な場合): ブラウザ API、イベントリスナー、または React フックが必要な場合のみ使用
• 継承よりもコンポジション: 小さな焦点を絞ったコンポーネントを組み合わせて複雑な UI を構築

API 設計パターン

• GET API なし: API ルートの代わりに Server Components を使用してデータフェッチ
• Server Actions を優先: フォーム送信とミューテーションには Server Actions を使用
• 外部統合用の API ルート: ウェブフックとサードパーティ統合にのみ POST/PATCH/PUT/DELETE を使用
• 型安全性: リクエスト/レスポンス検証には常に Zod スキーマを使用

Server Actions の配置方針

• 共有/ドメイン横断的な Server Actions は lib/actions/ に配置する
• ルート専用の小さな Server Actions は、必要に応じて該当ルート直下（例: app/(group)/feature/actions.ts）に置いてもよい
• ファイル命名は動詞ベースで、1 ファイル = 1 概念（例: user.ts, post.ts）を原則とし、index.ts で再エクスポートを許容

hooks / services / actions の使い分け

• hooks（クライアント専用）: React の状態・副作用・UI 連携に関するロジック。ブラウザ API、イベントハンドリング、フォーム状態など UI 寄りの責務
• services（サーバー/クライアント共有可）: ビジネスロジック、外部 API 呼び出し、プリミティブの組み合わせなどを純粋関数中心で実装。副作用は抽象化しテスト容易性を最優先
• actions（サーバー専用）: フォーム送信やミューテーションの入口。認証/認可、入力検証（Zod）、トランザクション制御、services のオーケストレーションを担当

ガイドライン:

• hooks は UI から actions を呼び出すための薄い橋渡しに留める
• ビジネスルールは可能な限り services に集約し、actions は I/O とオーケストレーションに専念
• services は副作用境界を明確化し、テストではモックで置き換え可能にする