プロジェクトの構造と組織化
このページでは、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 | 生成されたロボットファイル |
コンポーネントの階層
ルートセグメントの特別なファイルで定義されたReactコンポーネントは、特定の階層でレンダリングされます：
layout.jstemplate.jserror.js（React error boundary）loading.js（React suspense boundary）not-found.js（React error boundary）page.jsまたはネストされたlayout.js
ネストされたルートでは、セグメントのコンポーネントは親セグメントのコンポーネントの内側にネストされます。
プロジェクトの組織化
フォルダとファイルの規約とは別に、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。- プライベートフォルダを使用しない場合は、Next.jsの特別なファイル規約を知っておくと、予期しない命名の競合を防ぐのに役立ちます。
ルートグループ
ルートグループは、フォルダを括弧で囲むことで作成できます：(folderName)
これは、フォルダが組織的な目的であり、ルートのURLパスに含まれるべきではないことを示します。
ルートグループは以下のような場合に役立ちます：
- URLパスに影響を与えずにルートをグループ化する 例：サイトセクション、意図、チームごとに
- 同じルートセグメントレベルでネストされたレイアウトを有効にする：
srcディレクトリ
Next.jsは、アプリケーションコード（appを含む）をオプションのsrcディレクトリ内に保存することをサポートしています。これにより、アプリケーションコードをプロジェクトの設定ファイルから分離できます。設定ファイルは主にプロジェクトのrootに存在します。
一般的な戦略
次のセクションでは、一般的な戦略の非常に高レベルな概要を示します。最も簡単な結論は、自分とチームに合った戦略を選び、プロジェクト全体で一貫性を保つことです。
Good to know: 以下の例では、
componentsとlibフォルダを一般的なプレースホルダーとして使用しています。これらの名前には特別なフレームワークの意味はなく、プロジェクトによってはui、utils、hooks、stylesなどの他のフォルダを使用することがあります。
プロジェクトファイルをappの外に保存する
この戦略では、すべてのアプリケーションコードをプロジェクトのrootにある共有フォルダに保存し、appディレクトリを純粋にルーティングの目的で使用します。
プロジェクトファイルをapp内のトップレベルフォルダに保存する
この戦略では、すべてのアプリケーションコードをappディレクトリのrootにある共有フォルダに保存します。
プロジェクトファイルを機能またはルートごとに分割する
この戦略では、グローバルに共有されるアプリケーションコードをrootのappディレクトリに保存し、より特定のアプリケーションコードをそれを使用するルートセグメントに分割します。
