プロジェクト構造と組織化
このページでは、Next.jsにおけるすべてのフォルダとファイルの規約の概要と、プロジェクトを組織化するための推奨事項を提供します。
フォルダとファイルの規約
トップレベルフォルダ
トップレベルフォルダは、アプリケーションのコードと静的アセットを整理するために使用されます。
app | App Router |
pages | Pages Router |
public | 提供される静的アセット |
src | オプションのアプリケーションソースフォルダ |
トップレベルファイル
トップレベルファイルは、アプリケーションの設定、依存関係の管理、ミドルウェアの実行、モニタリングツールの統合、環境変数の定義に使用されます。
| Next.js | |
next.config.js | Next.jsの設定ファイル |
package.json | プロジェクトの依存関係とスクリプト |
instrumentation.ts | OpenTelemetryとInstrumentationファイル |
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 | .js .ts | 生成されたロボットファイル |
プロジェクトの組織化
Next.jsは、プロジェクトファイルの組織化や配置について特に意見を持ちませんが、プロジェクトを整理するためのいくつかの機能を提供しています。
コンポーネント階層
特別なファイルで定義されたコンポーネントは、特定の階層でレンダリングされます：
layout.jstemplate.jserror.js(React error boundary)loading.js(React suspense boundary)not-found.js(React error boundary)page.jsまたはネストされたlayout.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。- プライベートフォルダを使用しない場合は、予期しない命名競合を防ぐためにNext.jsの特別なファイル規約を知っておくと役立ちます。
ルートグループ
ルートグループは、フォルダを括弧で囲むことで作成できます：(folderName)
これは、フォルダが組織目的であり、ルートのURLパスに含まれないことを示します。
ルートグループは以下の目的で役立ちます：
- サイトセクション、意図、またはチームごとにルートを整理する。例：マーケティングページ、管理ページなど
- 同じルートセグメントレベルでネストされたレイアウトを有効にする：
srcディレクトリ
Next.jsは、アプリケーションコード（appを含む）をオプションのsrcディレクトリ内に保存することをサポートしています。これにより、プロジェクトの設定ファイルが主にプロジェクトのrootに存在するのに対し、アプリケーションコードを分離できます。
例
以下のセクションでは、一般的な戦略の非常に高レベルな概要を示します。最も簡単な結論は、あなたとあなたのチームに合った戦略を選び、プロジェクト全体で一貫性を保つことです。
Good to know: 以下の例では、
componentsとlibフォルダを一般的なプレースホルダーとして使用しています。これらの名前には特別なフレームワークの意味はなく、プロジェクトによってはui、utils、hooks、stylesなどの他のフォルダを使用することがあります。
プロジェクトファイルをappの外に保管する
この戦略では、すべてのアプリケーションコードをプロジェクトのrootにある共有フォルダに保存し、appディレクトリを純粋にルーティング目的のために使用します。
プロジェクトファイルをapp内のトップレベルフォルダに保管する
この戦略では、すべてのアプリケーションコードをappディレクトリのrootにある共有フォルダに保存します。
機能またはルートごとにプロジェクトファイルを分割する
この戦略では、グローバルに共有されるアプリケーションコードをrootのappディレクトリに保存し、より特定のアプリケーションコードをそれを使用するルートセグメントに分割します。
URLパスに影響を与えずにルートを整理する
URLに影響を与えずにルートを整理するには、関連するルートをまとめるためのグループを作成します。括弧内のフォルダはURLから省略されます（例：(marketing)または(shop)）。
(marketing)と(shop)内のルートは同じURL階層を共有していますが、それぞれのグループ内にlayout.jsファイルを追加することで、異なるレイアウトを作成できます。
特定のセグメントをレイアウトにオプトインする
特定のルートをレイアウトにオプトインするには、新しいルートグループ（例：(shop)）を作成し、同じレイアウトを共有するルート（例：accountとcart）をグループに移動します。グループ外のルート（例：checkout）はレイアウトを共有しません。
特定のルートでローディングスケルトンを選択する
特定のルートにloading.jsファイルを介してローディングスケルトンを適用するには、新しいルートグループ（例：/(overview)）を作成し、そのルートグループ内にloading.tsxを移動します。
これで、loading.tsxファイルはダッシュボード→概要ページにのみ適用され、URLパス構造に影響を与えることなく、他のダッシュボードページには適用されません。
複数のrootレイアウトを作成する
複数のrootレイアウトを作成するには、トップレベルのlayout.jsファイルを削除し、各ルートグループ内にlayout.jsファイルを追加します。これは、完全に異なるUIや体験を持つセクションにアプリケーションを分割するのに役立ちます。<html>と<body>タグは各rootレイアウトに追加する必要があります。
上記の例では、(marketing)と(shop)の両方が独自のrootレイアウトを持っています。