Next.js 15 + App Router スペシャリスト は何をしますか?
Quetrex 開発のための完全な Next.js 15 リファレンス。
このスキルは、Next.js 15 のすべての App Router パターンに関する包括的なガイダンスを提供し、エージェントがモダンな Next.js を初回から正しく実装できるようにします。
絶対ルール(絶対に違反しないこと)
これらのルールは交渉の余地がありません。違反するとビルドが壊れます。
1. 常に next/image の <Image> を使用する - <img> は絶対に使用しない
// ✅ 常にこうする
import Image from 'next/image'
<Image src="/logo.png" alt="Logo" width={200} height={100} />
<Image src={user.avatar} alt={user.name} width={40} height={40} />
// ❌ 絶対にしない - ビルドが失敗する
<img src="/logo.png" alt="Logo" />
<img src={user.avatar} alt={user.name} />
理由: Next.js の Image コンポーネントは、自動最適化、遅延ロード、レイアウトシフトの防止を提供します。ESLint は <img> の使用時にビルドを失敗させるように設定されています。
2. Server Components がデフォルト - 必要な場合のみ 'use client' を追加
3. 非同期 Client Components を絶対に作成しない
4. fetch() には常にキャッシュ戦略を指定する
このスキルを使用するタイミング
以下の作業時にこのスキルを使用します:
- 新しいルートまたはページの作成
- データフェッチの実装(Server Components vs Client Components)
- Server コンポーネントと Client コンポーネントの使い分け
- Server Actions とフォーム処理
- ストリーミングと Suspense
- メタデータと SEO
- ルートハンドラ(API ルート)
- キャッシュ戦略
- パフォーマンス最適化
完全なドキュメント
このスキルには、すべての Next.js 15 パターンを網羅した包括的なガイドが含まれています:
📁 App Router 完全ガイド
45以上の例でカバー:
- ファイルベースルーティング (page.tsx, layout.tsx, route.ts)
- 動的ルート ([id], [...slug], [[...slug]])
- ルートグループ ((group))
- プライベートフォルダ (_folder)
- ルートハンドラ (API ルート)
- レイアウトとテンプレート
- ローディング UI (loading.tsx)
- エラーバウンダリ (error.tsx, global-error.tsx)
- 404 ページ (not-found.tsx)
- パラレルルート (@folder)
- インターセプトルート ((.)folder)
- ルートセグメント設定 (dynamic, revalidate, runtime)
🔄 データフェッチ完全ガイド
35以上の例でカバー:
- Server Components でのデータフェッチ (async/await)
- Client Components でのデータフェッチ (useEffect, React Query, SWR)
- 並列データフェッチ (Promise.all)
- 逐次データフェッチ(ウォーターフォール防止)
- ストリーミングデータ (Suspense 境界)
- Server-Sent Events (Quetrex 音声用 SSE)
- データミューテーション (Server Actions)
- 楽観的更新 (useOptimistic)
- フォーム処理 (useFormStatus, useActionState)
- リクエスト重複排除
- データのプリロード
💾 キャッシュ戦略ガイド
35以上の例でカバー:
- リクエストのメモ化(自動重複排除)
- データキャッシュ (fetch キャッシュの挙動)
- フルルートキャッシュ(静的 vs 動的)
- ルーターキャッシュ(クライアントサイドキャッシュ)
- キャッシュ設定 (force-cache, no-store, revalidate)
- キャッシュタグ (revalidateTag, revalidatePath)
- オンデマンド再検証
- 時間ベースの再検証 (ISR)
- キャッシュデバッグテクニック
- キャッシュからのオプトアウト
⚡ Server Actions 完全ガイド
31以上の例でカバー:
- 基本的な Server Actions パターン
- フォームアクション(プログレッシブエンハンスメント)
- ボタンアクション(プログラムからの呼び出し)
- useFormStatus フック(ローディング状態)
- useActionState フック(状態管理)
- useOptimistic フック(楽観的 UI)
- アクション内のエラーハンドリング
- Zod を使ったバリデーション
- JSON 返却とリダイレクトの使い分け
- セキュリティ(認証、CSRF)
- レート制限
- データベーストランザクション
🎯 Metadata API ガイド
26以上の例でカバー:
- 静的メタデータ(エクスポートされたオブジェクト)
- 動的メタデータ (generateMetadata)
- ファイルベースのメタデータ (icon.png, opengraph-image.png)
- Open Graph メタデータ
- Twitter Cards
- JSON-LD 構造化データ
- Viewport 設定
- PWA マニフェスト
- Robots.txt
- Sitemap 生成
✅ パターンバリデータ
実行可能な Python スクリプトでチェック:
- Server Components がクライアント専用 API を使用していないか
- Client Components に 'use client' ディレクティブがあるか
- データフェッチが適切なキャッシュ戦略を使用しているか
- Server Actions が 'use server' でマークされているか
- Metadata API が正しく使用されているか
- 画像最適化 ( で ではない)
- 重いコンポーネントに対する動的インポート
実行方法: python validate-patterns.py /path/to/src
クイックリファレンス
Server Components と Client Components の使い分け判断ツリー
インタラクティブ性が必要ですか?(onClick, onChange など)
├─ YES → Client Components ('use client')
└─ NO → Server Components (デフォルト)
React フックが必要ですか?(useState, useEffect)
├─ YES → Client Components
└─ NO → Server Components
ブラウザ API が必要ですか?(window, localStorage)
├─ YES → Client Components
└─ NO → Server Components
データをフェッチする必要がありますか?
├─ Server Components を使用する(推奨)
└─ データがクライアント側でしか利用できない場合のみ Client Components を使用
コンポーネントは純粋に表示用ですか?
└─ Server Components(パフォーマンスが良い)
一般的なパターン
1. Server Components でのデータフェッチ
// app/projects/page.tsx
export default async function ProjectsPage() {
const projects = await db.project.findMany()
return <ProjectList projects={projects} />
}
2. インタラクティブ性を持つ Client Components
// components/ProjectCard.tsx
'use client'
import { useState } from 'react'
export function ProjectCard({ project }: Props) {
const [loading, setLoading] = useState(false)
const handleDelete = async () => {
setLoading(true)
await deleteProject(project.id)
setLoading(false)
}
return (
<div>
<h2>{project.name}</h2>
<button onClick={handleDelete} disabled={loading}>
Delete
</button>
</div>
)
}
3. フォームを使った Server Actions
// app/actions.ts
'use server'
export async function createProject(formData: FormData) {
const name = formData.get('name') as string
const project = await db.project.create({ data: { name } })
revalidatePath('/projects')
return { success: true, project }
}
// app/projects/new/page.tsx
import { createProject } from '@/app/actions'
export default function NewProjectPage() {
return (
<form action={createProject}>
<input name="name" required />
<button type="submit">Create</button>
</form>
)
}
4. Suspense を使ったストリーミング
// app/dashboard/page.tsx
import { Suspense } from 'react'
export default function DashboardPage() {
return (
<div>
<Suspense fallback={<ProjectsSkeleton />}>
<ProjectsAsync />
</Suspense>
<Suspense fallback={<UsersSkeleton />}>
<UsersAsync />
</Suspense>
</div>
)
}
async function ProjectsAsync() {
const projects = await fetchProjects() // 低速クエリ
return <ProjectList projects={projects} />
}
5. 動的メタデータ
// app/blog/[slug]/page.tsx
import type { Metadata } from 'next'
export async function generateMetadata({
params,
}: {
params: Promise<{ slug: string }>
}): Promise<Metadata> {
const { slug } = await params
const post = await fetchPost(slug)
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [post.coverImage],
},
}
}
Quetrex のベストプラクティス
1. まず Server Components を優先する
// ✅ 推奨: Server Components (デフォルト)
export default async function ProjectsPage() {
const projects = await fetchProjects()
return <ProjectList projects={projects} />
}
// ❌ 非推奨: 不要な Client Components
'use client'
export default function ProjectsPage() {
const [projects, setProjects] = useState([])
useEffect(() => {
fetchProjects().then(setProjects)
}, [])
return <ProjectList projects={projects} />
}
2. 適切なキャッシュ戦略を使用する
// 静的コンテンツ(永久キャッシュ)
const categories = await fetch('https://api.example.com/categories', {
cache: 'force-cache',
}).then(r => r.json())
// 動的コンテンツ(キャッシュなし)
const user = await fetch('https://api.example.com/me', {
cache: 'no-store',
}).then(r => r.json())
// ISR(1時間ごとに再検証)
const products = await fetch('https://api.example.com/products', {
next: { revalidate: 3600 },
}).then(r => r.json())
3. 適切なエラーバウンダリを実装する
// app/dashboard/error.tsx
'use client'
export default function DashboardError({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={reset}>Try again</button>
</div>
)
}
4. ローディング状態を使用する
// app/dashboard/loading.tsx
export default function DashboardLoading() {
return <DashboardSkeleton />
}
5. 画像を最適化する
// ✅ 推奨: next/image を使用
import Image from 'next/image'
export function ProjectCard({ project }) {
return (
<Image
src={project.image}
alt={project.name}
width={400}
height={300}
/>
)
}
// ❌ 非推奨: <img> タグを使用
export function ProjectCard({ project }) {
return <img src={project.image} alt={project.name} />
}
避けるべきよくある間違い
❌ 間違い 1: 非同期 Client Components
// ❌ 非推奨: これは構文エラーです
'use client'
export default async function BadComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
// ✅ 推奨: Server Components または useEffect を使用
export default async function GoodComponent() {
const data = await fetch('/api/data')
return <div>{data}</div>
}
❌ 間違い 2: Server Components でのクライアント API 使用
// ❌ 非推奨: Server Components はブラウザ API を使用できません
export default function BadComponent() {
const [state, setState] = useState(false) // エラー!
return <div>{state}</div>
}
// ✅ 推奨: 'use client' ディレクティブを追加
'use client'
export default function GoodComponent() {
const [state, setState] = useState(false)
return <div>{state}</div>
}
❌ 間違い 3: キャッシュ戦略の欠如
// ❌ 非推奨: キャッシュ動作が不明瞭
const data = await fetch('/api/data')
// ✅ 推奨: 明示的なキャッシュ戦略
const data = await fetch('/api/data', {
cache: 'no-store', // または 'force-cache'、{ next: { revalidate: 60 } }
})
❌ 間違い 4: を使用しない
// ❌ 非推奨: 最適化されていない画像
<img src="/logo.png" alt="Logo" />
// ✅ 推奨: Next.js 画像最適化を使用
<Image src="/logo.png" alt="Logo" width={200} height={100} />
トラブルシューティング
エラー: "You're importing a component that needs useState..."
解決策: コンポーネントファイルに 'use client' を追加します。
エラー: "async/await is not valid in Client Components"
解決策: 'use client' を削除するか、非同期コンポーネントの代わりに useEffect を使用します。
エラー: "process is not defined"
解決策: Client Components 内の環境変数には NEXT_PUBLIC_ プレフィックスが必要です。
エラー: "Headers already sent"
解決策: レスポンス送信後に headers() や cookies() を使用しないでください。ストリーミング開始前に呼び出してください。
公式ドキュメント
- Next.js 15.5 Docs: https://nextjs.org/docs
- App Router: https://nextjs.org/docs/app
- データフェッチ: https://nextjs.org/docs/app/building-your-application/data-fetching
- Server Actions: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- キャッシュ: https://nextjs.org/docs/app/building-your-application/caching
- メタデータ: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
- 例: https://github.com/vercel/next.js/tree/canary/examples
検証
パターンバリデータを実行してコードをチェックします:
python .claude/skills/nextjs-15-specialist/validate-patterns.py src/
バリデータは以下をチェックします:
- ✅ 非同期 Client Components(禁止)
- ✅ Server Components 内のクライアント API
- ✅ 'use client' ディレクティブの配置
- ✅ Server Actions の非同期関数
- ✅ 画像最適化
- ✅ 動的ルートのメタデータ
- ✅ 重いコンポーネントの動的インポート
- ✅ fetch のキャッシュ戦略
- ✅ ルートセグメント設定
サマリー
このスキルがあれば、以下のことが確実にできます:
- 正しいコンポーネントタイプ(Server vs Client)の選択
- 適切なデータフェッチパターンの実装
- 適切なキャッシュ戦略の使用
- Server Actions の正しい処理
- メタデータと SEO の最適化
- よくある Next.js の間違いの回避
- Quetrex のアーキテクチャガイドラインに従う
迷ったときは:
- 特定のガイドを読む(上記リンク)
- バリデータを実行する
- 公式の Next.js 15 ドキュメントを確認する
- Server Components をデフォルトにする
最終更新日: 2025-11-23 Next.js バージョン: 15.5 総例数: 150以上 総行数: 4,000行以上
