> ## Documentation Index > Fetch the complete documentation index at: https://atsushiishida.com/llms.txt > Use this file to discover all available pages before exploring further. # ファイルシステム規約 > Next.js App Routerの特殊ファイル規約とその使い方を理解する ## はじめに Next.js の [App Router](https://nextjs.org/docs/app) では、特定の名前を持つファイルが特殊な役割を果たします。このガイドでは、[ファイルシステム規約](https://nextjs.org/docs/app/api-reference/file-conventions)について、各ファイルの役割と実践的な使い方を学んでいきます。 ## ファイルシステム規約とは Next.js App Router では、`app`ディレクトリ内の特定のファイル名が予約されており、それぞれが特別な機能を提供します。これにより、ルーティング、レイアウト、エラーハンドリングなどが宣言的に実装できます。 ## 主要なファイル規約一覧 ### ルーティングファイル ``` app/ ├── layout.tsx # レイアウトを定義 ├── page.tsx # ページコンポーネントを定義 ├── loading.tsx # ローディング UI を定義 ├── error.tsx # エラー UI を定義 ├── global-error.tsx # グローバルエラー UI を定義 ├── not-found.tsx # 404 ページを定義 ├── template.tsx # テンプレートを定義 ├── default.js # 並行ルートのフォールバック（代替UI） └── route.tsx # API エンドポイントを定義 ``` ### メタデータファイル ``` app/ ├── favicon.ico # ファビコン ├── icon.(ico|jpg|jpeg|png|svg) # アプリアイコン ├── icon.tsx # 動的アイコン生成 ├── apple-icon.(jpg|jpeg|png) # Appleアイコン ├── apple-icon.tsx # 動的Appleアイコン生成 ├── opengraph-image.(jpg|jpeg|png|gif) # OG画像 ├── opengraph-image.tsx # 動的OG画像生成 ├── twitter-image.(jpg|jpeg|png|gif) # Twitter画像 ├── twitter-image.tsx # 動的Twitter画像生成 ├── manifest.json # PWAマニフェスト ├── manifest.ts # 動的マニフェスト生成 ├── robots.txt # クローラー制御 ├── robots.ts # 動的robots生成 ├── sitemap.xml # サイトマップ └── sitemap.ts # 動的サイトマップ生成 ``` ### その他の設定ファイル ``` ├── middleware.ts # ミドルウェアを定義（appディレクトリ外） └── app/ └── page.tsx # Route Segment Config をエクスポート可能 ``` ## page.tsx - ページの定義 ### 基本的な使い方 [`page.tsx`](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#pages)は、そのディレクトリを公開可能な URL として定義します。このファイルがないディレクトリは、URL としてアクセスできません。 ```typescript theme={null} // app/about/page.tsx export default function AboutPage() { return (

About ページ

このページは /about でアクセスできます

); } ``` ### Dynamic Route での使用 ```typescript theme={null} // app/blog/[slug]/page.tsx export default function BlogPost({ params }: { params: { slug: string } }) { return

記事: {params.slug}

; } ``` ## layout.tsx - 共有レイアウト ### 基本的な使い方 [`layout.tsx`](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts)は、複数のページで共有される UI を定義します。子ルートに自動的に適用され、ページ遷移時も再レンダリングされません。 ```typescript theme={null} // app/layout.tsx export default function RootLayout({ children, }: { children: React.ReactNode; }) { return (

{children}

); } ``` ### ネストされたレイアウトネストされたレイアウトとは、親のレイアウトの中に子のレイアウトが入れ子になっている構造のことです。Next.js では、ディレクトリ階層に沿って自動的にレイアウトがネストされます。 #### レイアウトの継承構造 ``` app/ ├── layout.tsx # ルートレイアウト（全ページ共通） └── dashboard/ ├── layout.tsx # ダッシュボードレイアウト ├── page.tsx # /dashboard ページ └── analytics/ ├── layout.tsx # 分析レイアウト └── page.tsx # /dashboard/analytics ページ ``` この構造では、`/dashboard/analytics` ページは以下の順序でレイアウトが適用されます： 1. **ルートレイアウト** (`app/layout.tsx`) - 全体の HTML 構造 2. **ダッシュボードレイアウト** (`app/dashboard/layout.tsx`) - ダッシュボード共通 UI 3. **分析レイアウト** (`app/dashboard/analytics/layout.tsx`) - 分析セクション固有 UI 4. **ページコンテンツ** (`app/dashboard/analytics/page.tsx`) - 実際のページ #### 実装例 ```typescript theme={null} // app/dashboard/layout.tsx export default function DashboardLayout({ children, }: { children: React.ReactNode; }) { return (

{/* ここに子レイアウトやページが挿入される */} {children}

); } ``` ```typescript theme={null} // app/dashboard/analytics/layout.tsx export default function AnalyticsLayout({ children, }: { children: React.ReactNode; }) { return (

データ分析

{/* フィルター UI */}

{/* ここに分析ページのコンテンツが挿入される */} {children}

); } ``` #### レンダリング結果 `/dashboard/analytics` にアクセスした場合の HTML 構造： ```html theme={null}

グローバルナビゲーション

データ分析

実際のページコンテンツ

``` #### メリット 1. **再利用性**: 共通の UI を複数のページで共有 2. **保守性**: レイアウトの変更が該当するセクションのみに影響 3. **パフォーマンス**: ページ遷移時にレイアウトは再レンダリングされない 4. **ユーザー体験**: 状態を保持したままページ間を移動可能 ## loading.tsx - ローディング UI ### 基本的な使い方 [`loading.tsx`](https://nextjs.org/docs/app/building-your-application/routing/loading-ui-and-streaming)は、ページやセグメントのロード中に表示される UI を定義します。[React Suspense](https://react.dev/reference/react/Suspense) を使用して自動的に適用されます。 ```typescript theme={null} // app/blog/loading.tsx export default function Loading() { return (

記事を読み込んでいます...

); } ``` ### スケルトンスクリーンの実装 #### スケルトンスクリーンとはスケルトンスクリーン（Skeleton Screen）とは、コンテンツの読み込み中に表示される仮のUIのことです。実際のコンテンツの構造やレイアウトを模倣したグレーや薄い色のボックスで構成され、以下のメリットがあります： * **体感速度の向上**: 真っ白な画面や単純なスピナーよりも読み込みが早く感じられる * **レイアウトシフトの防止**: コンテンツが読み込まれた際のレイアウトのずれを防ぐ * **ユーザー体験の向上**: 何が読み込まれるかを事前に示すことで、ユーザーの不安を軽減 #### 実装例商品一覧ページのスケルトンスクリーンの例： ```typescript theme={null} // app/products/loading.tsx export default function ProductsLoading() { return (

{/* 6個の商品カードのスケルトンを表示 */} {[...Array(6)].map((_, i) => (

{/* 商品画像のスケルトン */}

{/* 商品名のスケルトン */}

{/* 価格のスケルトン（短め） */}

))}

); } ``` #### CSS例 ```css theme={null} /* スケルトンスクリーンのスタイル */ .skeleton-card { border: 1px solid #e5e5e5; border-radius: 8px; padding: 16px; } .skeleton-image { width: 100%; height: 192px; background-color: #f3f4f6; border-radius: 4px; margin-bottom: 16px; } .skeleton-text { height: 16px; background-color: #f3f4f6; border-radius: 4px; margin-bottom: 8px; } .skeleton-text.short { width: 50%; } /* アニメーション効果 */ @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } } .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; } ``` #### ベストプラクティス 1. **実際のレイアウトに近づける**: 最終的なコンテンツと同じ構造にする 2. **適切な数の要素**: 実際に表示される要素数と合わせる 3. **アニメーション**: 微細なパルス効果で読み込み中であることを示す 4. **一貫性**: アプリケーション全体で統一されたスケルトンデザインを使用 ## error.tsx - エラーハンドリング ### 基本的な使い方 [`error.tsx`](https://nextjs.org/docs/app/building-your-application/routing/error-handling)は、エラーが発生した際のフォールバック UI を提供します。 > **フォールバック（Fallback）とは**\ > 何らかの問題が発生した時に代替として表示される UI のことです。通常の処理が失敗した場合に「代わりに」表示されるコンテンツを指します。自動的に React Error Boundary でラップされます。 ```typescript theme={null} // app/error.tsx "use client"; // Error components must be Client Components import { useEffect } from "react"; export default function Error({ error, reset, }: { error: Error & { digest?: string }; reset: () => void; }) { useEffect(() => { // エラーをログに記録 console.error(error); }, [error]); return (

エラーが発生しました

{error.message}

); } ``` ### セグメント固有のエラー処理 ```typescript theme={null} // app/dashboard/error.tsx "use client"; export default function DashboardError({ error, reset, }: { error: Error; reset: () => void; }) { return (

ダッシュボードでエラーが発生しました

); } ``` ## not-found.tsx - 404 ページ ### 基本的な使い方 [`not-found.tsx`](https://nextjs.org/docs/app/api-reference/file-conventions/not-found)は、特定のルートセグメントが見つからない場合に表示されます。 ```typescript theme={null} // app/not-found.tsx import Link from "next/link"; export default function NotFound() { return (

404 - ページが見つかりません

お探しのページは存在しません。

ホームに戻る

); } ``` ### notFound() 関数との連携 ```typescript theme={null} // app/blog/[slug]/page.tsx import { notFound } from "next/navigation"; async function getPost(slug: string) { const post = await fetchPost(slug); if (!post) { notFound(); // not-found.tsx を表示 } return post; } export default async function BlogPost({ params, }: { params: { slug: string }; }) { const post = await getPost(params.slug); return

{post.content}

; } ``` ## template.tsx - 再マウントされるレイアウト ### 基本的な使い方 [`template.tsx`](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#templates)は、`layout.tsx`と似ていますが、ページ間を移動する際（ナビゲーション時）に新しいインスタンスが作成されます。 #### ナビゲーション時とはナビゲーション時とは、ユーザーがページ間を移動する時のことです。具体的には以下のような場面を指します： * **リンククリック**: `` や `` タグをクリックして別のページに移動 * **ブラウザ操作**: 戻る・進むボタンを使用してページを移動 * **直接アクセス**: URLバーに直接URLを入力してページにアクセス * **プログラム実行**: `router.push()` や `router.replace()` などを実行 #### layout.tsx と template.tsx の違い両者の主な違いは、ページ遷移時のコンポーネントの扱いです： | ファイル | ページ遷移時の動作 | 状態の保持 | 使用場面 | | -------------- | --------------- | ---------- | ------------------------ | | `layout.tsx` | コンポーネントが再利用される | 状態が保持される | ナビゲーション、サイドバーなど永続的なUI | | `template.tsx` | 新しいインスタンスが作成される | 状態がリセットされる | ページ遷移アニメーション、毎回リセットしたい状態 | ```typescript theme={null} // app/template.tsx export default function Template({ children }: { children: React.ReactNode }) { return

{children}

; } ``` ### アニメーション付きテンプレート ```typescript theme={null} // app/dashboard/template.tsx "use client"; import { motion } from "framer-motion"; export default function DashboardTemplate({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` ## route.tsx - API エンドポイント ### 基本的な使い方 [`route.tsx`](https://nextjs.org/docs/app/building-your-application/routing/route-handlers)は、API エンドポイントを定義します。HTTP メソッドに対応する関数をエクスポートします。 #### API ルートの配置について `route.ts`（または `route.js`）ファイルは `app` ディレクトリ内のどこにでも配置できますが、実際の動作は配置場所によって異なります： | 配置場所 | URL | 動作 | 推奨度 | | ------------------------ | ------------ | ---------------- | ---------- | | `app/api/hello/route.ts` | `/api/hello` | API エンドポイントとして動作 | ✅ **推奨** | | `app/hello/route.ts` | `/hello` | API エンドポイントとして動作 | ⚠️ **非推奨** | **重要な注意点**： * `route.ts` と `page.ts` は**同じディレクトリに共存できません** * `app/hello/route.ts` がある場合、`app/hello/page.ts` は作成できません * 慣例的に API ルートは `app/api/` 配下に配置することが強く推奨されます #### 基本的な実装例 ```typescript theme={null} // app/api/hello/route.ts import { NextResponse } from "next/server"; export async function GET() { return NextResponse.json({ message: "Hello from API" }); } export async function POST(request: Request) { const data = await request.json(); return NextResponse.json({ message: "データを受信しました", data, }); } ``` #### api 配下以外に配置した場合の例 ```typescript theme={null} // app/webhook/route.ts (非推奨) import { NextResponse } from "next/server"; export async function POST(request: Request) { // この場合、URLは /webhook になります const data = await request.json(); return NextResponse.json({ received: true }); } ``` この配置方法は技術的には動作しますが、以下の理由で推奨されません： * **混乱を招く**: ページなのかAPIなのかが不明確 * **保守性の問題**: API とページが混在して管理が困難 * **チーム開発の問題**: 他の開発者が理解しにくい * **Next.js の慣例に反する**: 公式ドキュメントでも `api/` 配下を推奨 ### Dynamic Route での API ```typescript theme={null} // app/api/users/[id]/route.ts import { NextResponse } from "next/server"; export async function GET( request: Request, { params }: { params: { id: string } }, ) { const user = await getUser(params.id); if (!user) { return NextResponse.json( { error: "ユーザーが見つかりません" }, { status: 404 }, ); } return NextResponse.json(user); } ``` ## middleware.ts - リクエスト処理 ### 基本的な使い方 [`middleware.ts`](https://nextjs.org/docs/app/building-your-application/routing/middleware)は、リクエストが完了する前にコードを実行します。 ```typescript theme={null} // middleware.ts import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; export function middleware(request: NextRequest) { // 認証チェック const token = request.cookies.get("token"); if (!token && request.nextUrl.pathname.startsWith("/dashboard")) { return NextResponse.redirect(new URL("/login", request.url)); } return NextResponse.next(); } export const config = { matcher: "/dashboard/:path*", }; ``` ## default.js - 並行ルートのフォールバック ### 基本的な使い方 [`default.js`](https://nextjs.org/docs/app/building-your-application/routing/parallel-routes#defaultjs)は、並行ルートで初回ロード時やリロード時にマッチするセグメントがない場合のフォールバック（代替コンテンツ）を提供します。 ```typescript theme={null} // app/@team/default.tsx export default function TeamDefault() { return

チームを選択してください

; } ``` ## global-error.tsx - グローバルエラーハンドリング ### 基本的な使い方 [`global-error.tsx`](https://nextjs.org/docs/app/building-your-application/routing/error-handling#global-errorjs)は、ルートレイアウトでのエラーをキャッチします。production 環境でのみ有効です。 ```typescript theme={null} // app/global-error.tsx "use client"; export default function GlobalError({ error, reset, }: { error: Error & { digest?: string }; reset: () => void; }) { return (