プロジェクト構造と構成
このページでは、Next.jsにおけるすべてのフォルダとファイルの規約の概要と、プロジェクトを構成するための推奨事項を提供します。
フォルダとファイルの規約
トップレベルフォルダ
トップレベルフォルダは、アプリケーションのコードと静的アセットを整理するために使用されます。
トップレベルファイル
トップレベルファイルは、アプリケーションの設定、依存関係の管理、ミドルウェアの実行、監視ツールの統合、環境変数の定義に使用されます。
| 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 | 404 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 | 1レベル上でインターセプト |
(..)(..)folder | 2レベル上でインターセプト |
(...)folder | ルートからインターセプト |
メタデータファイル規約
アプリアイコン
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
プロジェクトの構成
Next.jsは、プロジェクトファイルをどのように整理して配置するかについて意見を強制しません。ただし、プロジェクトを整理するためのいくつかの機能を提供しています。
コンポーネント階層
特別なファイルで定義されたコンポーネントは、特定の階層でレンダリングされます：
layout.jstemplate.jserror.js(Reactエラー境界)loading.js(Reactサスペンス境界)not-found.js(Reactエラー境界)page.jsまたはネストされたlayout.js
コンポーネントはネストされたルートで再帰的にレンダリングされるため、ルートセグメントのコンポーネントはその親セグメントのコンポーネントの内側にネストされます。
コロケーション (Colocation)
appディレクトリでは、ネストされたフォルダがルート構造を定義します。各フォルダはURLパスの対応するセグメントにマッピングされるルートセグメントを表します。
ただし、ルート構造がフォルダで定義されていても、ルートセグメントにpage.jsまたはroute.jsファイルが追加されるまで、そのルートは公開アクセス可能になりません。
また、ルートが公開アクセス可能になった場合でも、page.jsまたはroute.jsが返すコンテンツのみがクライアントに送信されます。
これは、appディレクトリ内のルートセグメントに**プロジェクトファイルを安全にコロケーション（同居）**させても、誤ってルーティング可能にならないことを意味します。
知っておくと便利:
app内にプロジェクトファイルをコロケーションすることは可能ですが、必須ではありません。必要に応じてappディレクトリの外に保管することもできます。
プライベートフォルダ (Private folders)
フォルダ名の前にアンダースコアを付けることでプライベートフォルダを作成できます: _folderName
これは、そのフォルダがルーティングシステムから考慮されないプライベートな実装詳細であることを示し、フォルダとそのすべてのサブフォルダをルーティングから除外します。
appディレクトリ内のファイルはデフォルトで安全にコロケーション可能なため、コロケーションのためにプライベートフォルダは必須ではありません。ただし、以下の用途に役立ちます:
- UIロジックとルーティングロジックの分離
- プロジェクト全体およびNext.jsエコシステムで内部ファイルを一貫して整理
- コードエディタでのファイルの並べ替えとグループ化
- 将来のNext.jsファイル規約との名前衝突の回避
知っておくと便利:
- フレームワークの規約ではありませんが、プライベートフォルダ外のファイルにも同じアンダースコアパターンで「プライベート」マークを付けることを検討できます。
- フォルダ名の前に
%5F（アンダースコアのURLエンコード形式）を付けることで、アンダースコアで始まるURLセグメントを作成できます:%5FfolderName- プライベートフォルダを使用しない場合、Next.jsの特別なファイル規約を知っておくと、予期しない名前衝突を防ぐのに役立ちます。
ルートグループ (Route groups)
フォルダを括弧で囲むことでルートグループを作成できます: (folderName)
これは、そのフォルダが整理目的であり、ルートのURLパスに含まれないことを示します。
ルートグループは以下の用途に便利です:
- サイトセクション、意図、またはチームごとにルートを整理（例: マーケティングページ、管理ページなど）
- 同じルートセグメントレベルでネストされたレイアウトを有効化:
srcフォルダ
Next.jsはアプリケーションコード（appを含む）をオプションのsrcフォルダ内に保管することをサポートしています。これにより、アプリケーションコードとプロジェクトルートに主に存在する設定ファイルを分離できます。
例
以下のセクションでは、一般的な戦略の概要を非常に高レベルで説明します。最も単純なポイントは、あなたとチームにとって機能する戦略を選択し、プロジェクト全体で一貫性を保つことです。
知っておくと便利: 以下の例では、
componentsやlibフォルダを一般的なプレースホルダーとして使用しています。これらの名前には特別なフレームワークの意味はなく、ui、utils、hooks、stylesなどの他のフォルダを使用する場合もあります。
appの外にプロジェクトファイルを保管
この戦略では、すべてのアプリケーションコードをプロジェクトルートの共有フォルダに保管し、appディレクトリは純粋にルーティング目的のみに使用します。
app内のトップレベルフォルダにプロジェクトファイルを保管
この戦略では、すべてのアプリケーションコードをappディレクトリのルートにある共有フォルダに保管します。
機能やルートごとにプロジェクトファイルを分割
この戦略では、グローバルに共有されるアプリケーションコードをappディレクトリのルートに保管し、より特定のアプリケーションコードをそれらを使用するルートセグメントに分割します。
URLパスに影響を与えずにルートを整理
URLに影響を与えずにルートを整理するには、関連するルートをまとめて保持するグループを作成します。括弧内のフォルダはURLから除外されます（例: (marketing)や(shop)）。
(marketing)と(shop)内のルートは同じURL階層を共有していますが、各グループのフォルダ内にlayout.jsファイルを追加することで、グループごとに異なるレイアウトを作成できます。
特定のセグメントをレイアウトにオプトイン
特定のルートをレイアウトにオプトインするには、新しいルートグループ（例: (shop)）を作成し、同じレイアウトを共有するルート（例: accountとcart）をそのグループに移動します。グループ外のルート（例: checkout）はレイアウトを共有しません。
特定のルートにローディングスケルトンを適用
ローディングスケルトンをloading.jsファイルで特定のルートに適用するには、新しいルートグループ（例: /(overview)）を作成し、そのルートグループ内にloading.tsxを配置します。
これで、loading.tsxファイルはダッシュボード→概要ページにのみ適用され、URLパス構造に影響を与えずにすべてのダッシュボードページに適用されることはありません。
複数のルートレイアウトを作成
複数のルートレイアウトを作成するには、トップレベルのlayout.jsファイルを削除し、各ルートグループ内にlayout.jsファイルを追加します。これは、完全に異なるUIやエクスペリエンスを持つセクションにアプリケーションを分割する場合に便利です。<html>タグと<body>タグは各ルートレイアウトに追加する必要があります。
上記の例では、(marketing)と(shop)の両方が独自のルートレイアウトを持っています。