メインコンテンツまでスキップ

プロジェクト構造と組織化

このページでは、Next.jsにおけるすべてのフォルダとファイルの規約の概要と、プロジェクトを組織化するための推奨事項を提供します。

フォルダとファイルの規約

トップレベルフォルダ

トップレベルフォルダは、アプリケーションのコードと静的アセットを整理するために使用されます。

ルートセグメントからパスセグメントへの変換ルートセグメントからパスセグメントへの変換
appApp Router
pagesPages Router
public提供される静的アセット
srcオプションのアプリケーションソースフォルダ

トップレベルファイル

トップレベルファイルは、アプリケーションの設定、依存関係の管理、ミドルウェアの実行、モニタリングツールの統合、環境変数の定義に使用されます。

Next.js
next.config.jsNext.jsの設定ファイル
package.jsonプロジェクトの依存関係とスクリプト
instrumentation.tsOpenTelemetryとInstrumentationファイル
middleware.tsNext.jsリクエストミドルウェア
.env環境変数
.env.localローカル環境変数
.env.production本番環境変数
.env.development開発環境変数
.eslintrc.jsonESLintの設定ファイル
.gitignore無視するGitファイルとフォルダ
next-env.d.tsNext.js用のTypeScript宣言ファイル
tsconfig.jsonTypeScriptの設定ファイル
jsconfig.jsonJavaScriptの設定ファイル

ルーティングファイル

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 .tsAPIエンドポイント
template.js .jsx .tsx再レンダリングされるレイアウト
default.js .jsx .tsxパラレルルートのフォールバックページ

ネストされたルート

folderルートセグメント
folder/folderネストされたルートセグメント

動的ルート

[folder]動的ルートセグメント
[...folder]キャッチオールルートセグメント
[[...folder]]オプショナルキャッチオールルートセグメント

ルートグループとプライベートフォルダ

(folder)ルーティングに影響を与えずにルートをグループ化
_folderフォルダとすべての子セグメントをルーティングから除外

パラレルルートとインターセプトルート

@folder名前付きスロット
(.)folder同じレベルでのインターセプト
(..)folder1レベル上でのインターセプト
(..)(..)folder2レベル上でのインターセプト
(...)folderrootからのインターセプト

メタデータファイルの規約

アプリアイコン

favicon.icoファビコンファイル
icon.ico .jpg .jpeg .png .svgアプリアイコンファイル
icon.js .ts .tsx生成されたアプリアイコン
apple-icon.jpg .jpeg, .pngAppleアプリアイコンファイル
apple-icon.js .ts .tsx生成されたAppleアプリアイコン

Open GraphとTwitter画像

opengraph-image.jpg .jpeg .png .gifOpen Graph画像ファイル
opengraph-image.js .ts .tsx生成されたOpen Graph画像
twitter-image.jpg .jpeg .png .gifTwitter画像ファイル
twitter-image.js .ts .tsx生成されたTwitter画像

SEO

sitemap.xmlサイトマップファイル
sitemap.js .ts生成されたサイトマップ
robots.txtロボットファイル
robots.js .ts生成されたロボットファイル

プロジェクトの組織化

Next.jsは、プロジェクトファイルの組織化や配置について特に意見を持ちませんが、プロジェクトを整理するためのいくつかの機能を提供しています。

コンポーネント階層

特別なファイルで定義されたコンポーネントは、特定の階層でレンダリングされます:

  • layout.js
  • template.js
  • error.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ファイルが追加されるまでルートが公開されないことを示す図ルートセグメントにpage.jsまたはroute.jsファイルが追加されるまでルートが公開されないことを示す図

そして、ルートが公開されると、page.jsまたはroute.jsによって返されるコンテンツのみがクライアントに送信されます。

page.jsとroute.jsファイルがルートを公開可能にすることを示す図page.jsとroute.jsファイ��ルがルートを公開可能にすることを示す図

これは、appディレクトリ内のルートセグメント内にプロジェクトファイル安全に配置でき、誤ってルーティングされることがないことを意味します。

page.jsまたはroute.jsファイルを含むセグメントに配置されたプロジェクトファイルがルーティングされないことを示す図page.jsまたはroute.jsファイルを含むセグメントに配置されたプロジェクトファイルがルーティングされないことを示す図

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に存在するのに対し、アプリケーションコードを分離できます。

`src`ディレクトリを使用したフォルダ構造の例`src`ディレクトリを使用したフォルダ構造の例

以下のセクションでは、一般的な戦略の非常に高レベルな概要を示します。最も簡単な結論は、あなたとあなたのチームに合った戦略を選び、プロジェクト全体で一貫性を保つことです。

Good to know: 以下の例では、componentslibフォルダを一般的なプレースホルダーとして使用しています。これらの名前には特別なフレームワークの意味はなく、プロジェクトによってはuiutilshooksstylesなどの他のフォルダを使用することがあります。

プロジェクトファイルをappの外に保管する

この戦略では、すべてのアプリケーションコードをプロジェクトのrootにある共有フォルダに保存し、appディレクトリを純粋にルーティング目的のために使用します。

appの外にプロジェクトファイルを保管するフォルダ構造の例appの外にプロジェクトファイルを保管するフォルダ構造の例

プロジェクトファイルをapp内のトップレベルフォルダに保管する

この戦略では、すべてのアプリケーションコードをappディレクトリのrootにある共有フォルダに保存します。

app内にプロジェクトファイルを保管するフォルダ構造の例app内にプロジェクトファイルを保管するフォルダ構造の例

機能またはルートごとにプロジェクトファイルを分割する

この戦略では、グローバルに共有されるアプリケーションコードをrootのappディレクトリに保存し、より特定のアプリケーションコードをそれを使用するルートセグメントに分割します。

機能またはルートごとにプロジェクトファイルを分割するフォルダ構造の例機能またはルートごとにプロジェクトファイルを分割するフォルダ構造の例

URLパスに影響を与えずにルートを整理する

URLに影響を与えずにルートを整理するには、関連するルートをまとめるためのグループを作成します。括弧内のフォルダはURLから省略されます(例:(marketing)または(shop))。

ルートグループを使用したルートの整理ルートグループを使用したルートの整理

(marketing)(shop)内のルートは同じURL階層を共有していますが、それぞれのグループ内にlayout.jsファイルを追加することで、異なるレイアウトを作成できます。

複数のレイアウトを持つルートグループ複数のレイアウトを持つルートグループ

特定のセグメントをレイアウトにオプトインする

特定のルートをレイアウトにオプトインするには、新しいルートグループ(例:(shop))を作成し、同じレイアウトを共有するルート(例:accountcart)をグループに移動します。グループ外のルート(例:checkout)はレイアウトを共有しません。

オプトインレイアウトを持つルートグループオプトインレイアウトを持つルートグループ

特定のルートでローディングスケルトンを選択する

特定のルートにloading.jsファイルを介してローディングスケルトンを適用するには、新しいルートグループ(例:/(overview))を作成し、そのルートグループ内にloading.tsxを移動します。

ルートグループ内にloading.tsxとpage.tsxがあるフォルダ構造ルートグループ内にloading.tsxとpage.tsxがあるフォルダ構造

これで、loading.tsxファイルはダッシュボード→概要ページにのみ適用され、URLパス構造に影響を与えることなく、他のダッシュボードページには適用されません。

複数のrootレイアウトを作成する

複数のrootレイアウトを作成するには、トップレベルのlayout.jsファイルを削除し、各ルートグループ内にlayout.jsファイルを追加します。これは、完全に異なるUIや体験を持つセクションにアプリケーションを分割するのに役立ちます。<html><body>タグは各rootレイアウトに追加する必要があります。

複数のrootレイアウトを持つルートグループ複数のrootレイアウトを持つルートグループ

上記の例では、(marketing)(shop)の両方が独自のrootレイアウトを持っています。