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は副作用境界を明確化し、テストではモックで置き換え可能にする