プロジェクト構造と組織化
このページでは、Next.jsにおけるフォルダとファイルの規約、およびプロジェクトを組織化するためのヒントを紹介します。
フォルダとファイルの規約
最上位フォルダ
最上位フォルダは、アプリケーションのコードと静的アセットを整理するために使用されます。
app | App Router |
pages | Pages Router |
public | サーブされる静的アセット |
src | オプションのアプリケーションソースフォルダ |
最上位ファイル
最上位ファイルは、アプリケーションの設定、依存関係の管理、ミドルウェアの実行、モニタリングツールの統合、環境変数の定義に使用されます。
| Next.js | |
next.config.js | Next.jsの設定ファイル |
package.json | プロジェクトの依存関係とスクリプト |
instrumentation.ts | OpenTelemetryとインストゥルメンテーションファイル |
middleware.ts | Next.jsリクエストミドルウェア |
.env | 環境変数 |
.env.local | ローカル環境変数 |
.env.production | 本番環境変数 |
.env.development | 開発環境変数 |
.eslintrc.json | ESLintの設定ファイル |
.gitignore | Gitで無視されるファイルとフォルダ |
next-env.d.ts | Next.jsのTypeScript宣言ファイル |
tsconfig.json | TypeScriptの設定ファイル |
jsconfig.json | JavaScriptの設定ファイル |
ルーティングファイル
layout | .js .jsx .tsx | レイアウト |
page | .js .jsx .tsx | ページ |
loading | .js .jsx .tsx | ローディングUI |
not-found | .js .jsx .tsx | 見つからないUI |
error | .js .jsx .tsx | エラーUI |
global-error | .js .jsx .tsx | グローバルエラーUI |
route | .js .ts | APIエンドポイント |
template | .js .jsx .tsx | 再レンダリングされたレイアウト |
default | .js .jsx .tsx | パラレルルートのフェールバックページ |
ネストルート
folder | ルートセグメント |
folder/folder | ネストルートセグメント |
動的ルート
[folder] | 動的ルートセグメント |
[...folder] | キャッチオールルートセグメント |
[[...folder]] | オプションのキャッチオールルートセグメント |
ルートグループとプライベートフォルダ
(folder) | ルーティングに影響を与えずにルートをグループ化 |
_folder | フォルダとすべての子セグメントをルーティングから除外 |
パラレルルートとインターセプタールート
@folder | 名前付きスロット |
(.)folder | 同じレベルでインターセプト |
(..)folder | 1レベル上でインターセプト |
(..)(..)folder | 2レベル上でインターセプト |
(...)folder | rootからインターセプト |
メタデータファイルの規約
アプリのアイコン
favicon | .ico | ファビコンファイル |
icon | .ico .jpg .jpeg .png .svg | アプリアイコンファイル |
icon | .js .ts .tsx | 生成されたアプリアイコン |
apple-icon | .jpg .jpeg, .png | Appleアプリアイコンファイル |
apple-icon | .js .ts .tsx | 生成されたAppleアプリアイコン |
Open GraphとTwitterの画像
opengraph-image | .jpg .jpeg .png .gif | Open Graph画像ファイル |
opengraph-image | .js .ts .tsx | 生成されたOpen Graph画像 |
twitter-image | .jpg .jpeg .png .gif | Twitter画像ファイル |
twitter-image | .js .ts .tsx | 生成されたTwitter画像 |
SEO
sitemap | .xml | サイトマップファイル |
sitemap | .js .ts | 生成されたサイトマップ |
robots | .txt | Robotsファイル |
robots | .js .ts | 生成されたRobotsファイル |
プロジェクトの組織化
Next.jsは、フォルダとファイルの規約以外では、プロジェクトファイルの組織化や配置方法に対して特に意見を持っていません。しかし、プロジェクトを整理するためのいくつかの機能を提供しています。
コロケーション
appディレクトリ内では、ネストフォルダ階層がルート構造を定義します。各フォルダは、URLパス内の対応するセグメントにマッピングされるルートセグメントを表しています。
ただし、ルート構造はフォルダを通して定義されますが、page.jsまたはroute.jsファイルがルートセグメントに追加されるまでは、ルートは公開されません。
そして、ルートが公開されるときも、クライアントに送信されるのはpage.jsまたはroute.jsによって返されるコンテンツだけです。
これにより、プロジェクトファイルをappディレクトリ内のルートセグメントに安全にコロケーションすることができ、誤ってルートになることはありません。
Good to know:
app内にプロジェクトファイルをコロケーションできますが、必ずしもそうする必要はありません。希望する場合は、appディレクトリの外に保持することもできます。
プライベートフォルダ
フォルダ名の前にアンダースコアを付けることで、プライベートフォルダを作成することができます: _folderName
これはフォルダがプライベートな実装の詳細であることを示し、ルーティングシステムによって考慮されるべきではなく、フォルダとそのサブフォルダ全体がルーティングから除外されることを意味します。
appディレクトリ内のファイルはデフォルトで安全にコロケーションされるため、コロケーションのためにプライベートフォルダは必要ありません。しかし、次のような場合に有用です：
- UIロジックとルーティングロジックを分離する
- プロジェクトやNext.jsエコシステム全体で内部ファイルを一貫して整理する
- コードエディタでファイルを整理しグループ化する
- 将来のNext.jsのファイル規約との命名の衝突を避ける
Good to know:
- フレームワークの規約ではありませんが、プライベートフォルダの外にあるファイルも同じアンダースコアのパターンを使うことで「プライベート」とマークすることを検討するかもしれません。
- フォルダ名の前に
%5F（アンダースコアのURLエンコード形式）を付けることで、アンダースコアで始まるURLセグメントを作成できます：
%5FfolderName- プライベートフォルダを使用しない場合、Unexpectedな命名の衝突を防ぐためにNext.jsの特別なファイルの規約を知っておくと便利です。
ルートグループ
ルートグループは、フォルダを丸括弧で囲むことで作成できます：(folderName)
これはフォルダが整理目的であり、ルートのURLパスには含まれないことを示します。
ルートグループは次のような場合に有用です：
- サイトのセクション、目的、チームごとにルートをグループ化します
- 同じルートセグメントレベルでネストされたレイアウトを可能にする：
srcディレクトリ
Next.jsは、アプリケーションコード（appを含む）をオプションのsrcディレクトリ内に保存することをサポートしています。これにより、プロジェクトの構成ファイルが主にプロジェクトのルートにあるのに対して、アプリケーションコードを分離します。
一般的な戦略
次のセクションでは、一般的な戦略の非常に高レベルな概要を紹介します。最も簡単な要点は、自分やチームにとって効果的な戦略を選び、プロジェクト全体で一貫性を保つことです。
Good to know: 以下の例では、
componentsやlibフォルダを一般的なプレースホルダとして使用しており、この命名には特別なフレームワークの意味はありません。プロジェクトによってはui、utils、hooks、stylesなどのフォルダを使用することがあります。
appの外にプロジェクトファイルを格納する
この戦略では、すべてのアプリケーションコードをプロジェクトのルート内の共有フォルダに保存し、appディレクトリを純粋にルーティング目的のために保ちます。
app内部の最上位フォルダ内にプロジェクトファイルを格納する
この戦略では、アプリケーションコードをappディレクトリのルート内の共有フォルダに保存します。
機能またはルートごとにプロジェクトファイルを分割する
この戦略では、グローバルに共有されるアプリケーションコードをappディレクトリのルートに保存し、より具体的なアプリケーションコードをルートセグメントごとに分割して使用します。
