nextjs-app-router-conventions

name	nextjs-app-router-conventions
description	Next.js App Router conventions covering file-based routing, caching strategies, Server Actions, Metadata API, and framework-specific patterns. Auto-triggers when working within Next.js App Router projects on files matching `src/**/*.tsx`, `src/**/*.ts`, `proxy.ts`, or `next.config.*`. Covers file-based routing, caching, Server Actions, Metadata API, and framework-specific patterns.

Next.js App Router Conventions

Next.js App Router のフレームワーク固有規約集。ファイルベースルーティング、キャッシュ戦略、Server Actions、Metadata API に関するルールを定義する。

When to Apply

以下のいずれかに該当する作業時に自動で参照する：

• 次のパターンに一致するファイルの作成・修正
  • src/**/*.tsx
  • src/**/*.ts
  • proxy.ts
  • next.config.*
• ページ・レイアウトの作成
• Server Actions の実装
• Route Handler の作成
• キャッシュ戦略の設計
• Metadata / OGP の設定
• Proxy の実装

Compatibility

Next.js 16+

Rule Categories

Category	Prefix
ファイル規約	file-
Server Actions	actions-
キャッシュ戦略	cache-
Metadata / SEO	metadata-
ルーティングパターン	routing-
Proxy	proxy-

Quick Reference

ファイル規約

• file-layout-no-rerender - layout.tsx は再レンダリングされない前提で設計する
• file-loading-per-segment - 各ルートセグメントに適切な loading.tsx を配置する
• file-error-recovery - error.tsx でリカバリ可能なUIを提供する
• file-not-found-custom - not-found.tsx でユーザーフレンドリーな404を作る
• file-template-vs-layout - 再マウントが必要な場合は template.tsx を使う
• file-server-only-guard - サーバー専用モジュールには import "server-only" を付ける

Server Actions

• actions-validation - Server Action の入力は必ずサーバー側でバリデーションする
• actions-auth-check - Server Action 内で認証・認可チェックを行う
• actions-revalidate - データ変更後は適切な revalidation を実行する
• actions-error-handling - Server Action のエラーはクライアントに安全に返す
• actions-progressive-enhancement - JavaScript 無効でもフォームが動作するようにする

キャッシュ戦略

• cache-understand-layers - 4つのキャッシュレイヤーを理解して設計する
• cache-avoid-unnecessary-loading - ナビゲーション時に不要なローディングを出さない

Metadata / SEO

• metadata-generate-dynamic - 動的ページでは generateMetadata を使う
• metadata-opengraph-image - OGP画像は opengraph-image.tsx で動的生成する
• metadata-canonical-url - canonical URL を明示的に設定する

データ取得

• fetching-no-route-handler-hop - Server Component から自分自身の Route Handler を呼ばない

ルーティングパターン

• routing-group-by-feature - Route Groups で機能単位にグルーピングする
• routing-catch-all-carefully - catch-all routes の優先順位に注意する

Proxy

• proxy-lightweight - Proxy は軽量に保つ（重い処理を入れない）
• proxy-matcher - matcher で対象パスを限定する
• proxy-no-db - Proxy 内でDBアクセスしない

How to Use

個別ルールの詳細は rules/ ディレクトリ内のファイルを参照。上記 Quick Reference のリンクから各ルールにアクセスできる。

各ルールファイルには以下が含まれる：

• ルールの説明と根拠
• Bad: 間違ったコード例
• Good: 正しいコード例
• Next.js バージョン固有の注意点