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