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

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

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

トップレベルフォルダ

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


`app`	App Router
`pages`	Pages Router
`public`	提供される静的アセット
`src`	オプションのアプリケーションソースフォルダ

トップレベルファイル

トップレベルファイルは、アプリケーションの設定、依存関係の管理、プロキシの実行、監視ツールの統合、環境変数の定義に使用されます。


Next.js
`next.config.js`	Next.jsの設定ファイル
`package.json`	プロジェクトの依存関係とスクリプト
`instrumentation.ts`	OpenTelemetryとInstrumentationファイル
`proxy.ts`	Next.jsリクエストプロキシ
`.env`	環境変数
`.env.local`	ローカル環境変数
`.env.production`	本番環境変数
`.env.development`	開発環境変数
`eslint.config.mjs`	ESLint 設定ファイル
`.gitignore`	Gitで無視するファイルとフォルダ
`next-env.d.ts`	Next.jsのTypeScript宣言ファイル
`tsconfig.json`	TypeScriptの設定ファイル
`jsconfig.json`	JavaScriptの設定ファイル

ルーティングファイル

ルートを公開するにはpageを追加し、ヘッダー、ナビゲーション、フッターなどの共有UIにはlayoutを、スケルトンにはloadingを、エラーバウンダリにはerrorを、APIにはrouteを使用します。


`layout`	`.js` `.jsx` `.tsx`	レイアウト
`page`	`.js` `.jsx` `.tsx`	ページ
`loading`	`.js` `.jsx` `.tsx`	Loading UI
`not-found`	`.js` `.jsx` `.tsx`	Not Found UI
`error`	`.js` `.jsx` `.tsx`	Error UI
`global-error`	`.js` `.jsx` `.tsx`	Global Error UI
`route`	`.js` `.ts`	APIエンドポイント
`template`	`.js` `.jsx` `.tsx`	再レンダリングされるレイアウト
`default`	`.js` `.jsx` `.tsx`	Parallel Routeフォールバックページ

ネストされたルート

フォルダはURLセグメントを定義します。フォルダをネストするとセグメントがネストされます。任意のレベルのレイアウトは、その子セグメントをラップします。pageまたはrouteファイルが存在するとルートが公開されます。

パス	URLパターン	注記
`app/layout.tsx`	—	すべてのルートをラップするルートレイアウト
`app/blog/layout.tsx`	—	`/blog`とその子孫をラップ
`app/page.tsx`	`/`	公開ルート
`app/blog/page.tsx`	`/blog`	公開ルート
`app/blog/authors/page.tsx`	`/blog/authors`	公開ルート

動的ルート

セグメントを角括弧でパラメータ化します。単一のパラメータには[segment]を、キャッチオールには[...segment]を、オプションのキャッチオールには[[...segment]]を使用します。値にはparamsプロップを使用してアクセスします。

パス	URLパターン
`app/blog/[slug]/page.tsx`	`/blog/my-first-post`
`app/shop/[...slug]/page.tsx`	`/shop/clothing`、`/shop/clothing/shirts`
`app/docs/[[...slug]]/page.tsx`	`/docs`、`/docs/layouts-and-pages`、`/docs/api-reference/use-router`

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

ルートグループ(group)でコードを組織化するとURLは変わらず、プライベートフォルダ_folderでルート不可のファイルを配置できます。

パス	URLパターン	注記
`app/(marketing)/page.tsx`	`/`	グループはURLから除外
`app/(shop)/cart/page.tsx`	`/cart`	`(shop)`内でレイアウトを共有
`app/blog/_components/Post.tsx`	—	ルート不可；UIユーティリティの安全な場所
`app/blog/_lib/data.ts`	—	ルート不可；ユーティリティの安全な場所

Parallel RoutesとIntercepted Routes

これらの機能は、スロットベースのレイアウトやモーダルルーティングなど、特定のUIパターンに適しています。

名前付きスロットをレンダリングするには@slotを使用します。インターセプトパターンを使用すると、URLを変更せずに別のルートを現在のレイアウト内にレンダリングできます。例えば、詳細ビューをリスト上のモーダルとして表示する場合です。

パターン（ドキュメント）	意味	典型的なユースケース
`@folder`	名前付きスロット	サイドバー＋メインコンテンツ
`(.)folder`	同じレベルをインターセプト	兄弟ルートをモーダルでプレビュー
`(..)folder`	親をインターセプト	親の子をオーバーレイとして開く
`(..)(..)folder`	2つのレベルをインターセプト	深くネストされたオーバーレイ
`(...)folder`	ルートからインターセプト	任意のルートを現在のビューに表示

メタデータファイル規則

アプリアイコン


`favicon`	`.ico`	Faviconファイル
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	アプリアイコンファイル
`icon`	`.js` `.ts` `.tsx`	生成されたアプリアイコン
`apple-icon`	`.jpg` `.jpeg`、`.png`	Apple App Iconファイル
`apple-icon`	`.js` `.ts` `.tsx`	生成されたApple App Icon

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ファイル
`sitemap`	`.js` `.ts`	生成されたSitemap
`robots`	`.txt`	Robotsファイル
`robots`	`.js` `.ts`	生成されたRobotsファイル

プロジェクトの組織化

Next.jsは、プロジェクトファイルをどのように組織化および配置するかについて、特定の見方を持っていません。ただし、プロジェクトを組織化するのに役立つ機能が用意されています。

コンポーネント階層

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

layout.js
template.js
error.js（Reactエラーバウンダリ）
loading.js（React Suspenseバウンダリ）
not-found.js（「見つかりません」UIのReactエラーバウンダリ）
page.jsまたはネストされたlayout.js

Component Hierarchy for File Conventions

コンポーネントはネストされたルート内で再帰的にレンダリングされます。つまり、ルートセグメントのコンポーネントは、その親セグメントのコンポーネント内部にネストされます。

Nested File Conventions Component Hierarchy

配置

appディレクトリでは、ネストされたフォルダはルート構造を定義します。各フォルダはルートセグメントを表し、URLパスの対応するセグメントにマップされます。

ただし、ルート構造はフォルダを通じて定義されていますが、ルートセグメントにpage.jsまたはroute.jsファイルが追加されるまで、ルートは公開されません。

A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment.

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

A diagram showing how page.js and route.js files make routes publicly accessible.

つまり、プロジェクトファイルをappディレクトリ内のルートセグメント内に安全に配置でき、誤ってルート化されることはありません。

A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

補足：app内にプロジェクトファイルを配置することができますが、する必要はありません。お好みでしたら、appディレクトリの外に保存することができます。

プライベートフォルダ

プライベートフォルダは、フォルダの先頭にアンダースコアを付けることで作成できます。_folderName

これは、フォルダがプライベートな実装の詳細であることを示し、ルーティングシステムによって考慮されるべきではなく、フォルダとそのすべてのサブフォルダをルーティングから除外します。

An example folder structure using private folders

appディレクトリ内のファイルはデフォルトで安全に配置できるため、配置のためにプライベートフォルダは必須ではありません。ただし、次の場合に役立つことがあります。

UIロジックをルーティングロジックから分離する。
プロジェクト全体とNext.jsエコシステム全体で内部ファイルを一貫して組織化する。
コードエディタでファイルをソートおよびグループ化する。
将来のNext.jsファイル規則との潜在的な命名競合を回避する。

補足：

フレームワークの規則ではありませんが、同じアンダースコアパターンを使用して、プライベートフォルダの外側のファイルを「プライベート」としてマークすることも検討できます。

アンダースコア（URL符号化形式の%5F）の先頭にフォルダ名を付けることで、アンダースコアで始まるURLセグメントを作成できます。%5FfolderName。

プライベートフォルダを使用しない場合、Next.jsの特殊なファイル規則を理解して、予期しない命名競合を防ぐことをお勧めします。

ルートグループ

ルートグループは、フォルダを括弧で囲むことで作成できます。(folderName)

これは、フォルダが組織化の目的であり、ルートのURLパスに含められるべきではないことを示します。

An example folder structure using route groups

ルートグループは以下の目的に役立ちます。

サイトセクション、意図、またはチーム別にルートを組織化する。例えば、マーケティングページ、管理者ページなど。
同じルートセグメントレベルでネストされたレイアウトを有効にする。
- 同じセグメント内に複数のネストされたレイアウトを作成します。複数のルートレイアウトを含めます
- 共通セグメント内のルートのサブセットにレイアウトを追加します

`src`フォルダ

Next.jsは、アプリケーションコード（appを含む）をオプションのsrcフォルダ内に保存することをサポートしています。これにより、アプリケーションコードをプロジェクト設定ファイルから分離します。プロジェクト設定ファイルはほとんどプロジェクトのルートに保存されています。

An example folder structure with the `src` folder

例

以下のセクションでは、一般的な戦略の非常に高いレベルの概要を列挙します。最も単純な結論は、ユーザーとチームに適した戦略を選択し、プロジェクト全体で一貫性を保つことです。

補足：下の例では、componentsとlibフォルダを一般化されたプレースホルダーとして使用しています。その命名には特別なフレームワークの意味がなく、プロジェクトはui、utils、hooks、stylesなどの他のフォルダを使用できます。