nextjs

Next.js App Router - 本番環境向けパターン

バージョン: Next.js 16.2.0 React バージョン: 19.2.0 Node.js: 20.9+ 最終確認日: 2025-11-21

目次

1. このスキルを使用する場面
2. このスキルを使用しない場面
3. Next.js 16 の破壊的変更
4. Cache Components とキャッシュ API
5. サーバーコンポーネント
6. サーバーアクション
7. ルートハンドラー
8. React 19.2 の機能
9. メタデータ API
10. 画像とフォントの最適化
11. 重大なエラーの上位 5 件
12. パフォーマンスパターン
13. TypeScript の設定

---

このスキルを使用する場面

次のことが必要な場合に、このスキルを使用してください。

• Next.js 16 App Router のパターン（レイアウト、読み込み、エラーバウンダリー、ルーティング）
• サーバーコンポーネントのベストプラクティス（データ取得、合成、ストリーミング）
• サーバーアクションのパターン（フォーム、ミューテーション、再検証、エラー処理）
• "use cache" ディレクティブを使用した Cache Components（Next.js 16 の新機能）
• 新しいキャッシュ API：revalidateTag()、updateTag()、refresh()（Next.js 16 で更新）
• Next.js 15 から 16 への移行（非同期 params、proxy.ts、並列ルート）
• ルートハンドラー（API エンドポイント、Webhook、ストリーミングレスポンス）
• プロキシパターン（Next.js 16 では proxy.ts が middleware.ts に置き換わります）
• 非同期ルート params（params、searchParams、cookies()、headers() が非同期になりました）
• default.js を使用した並列ルート（Next.js 16 での破壊的変更）
• React 19.2 の機能（View Transitions、useEffectEvent()、React Compiler）
• メタデータ API（SEO、Open Graph、Twitter カード、サイトマップ）
• 画像の最適化（Next.js 16 でデフォルト設定が更新された next/image）
• パフォーマンスの最適化（遅延読み込み、コード分割、PPR、ISR）

このスキルを使用しない場面

次の用途には、このスキルを使用しないでください。

• Cloudflare Workers へのデプロイ → cloudflare-nextjs スキルを使用してください（OpenNext アダプター：@opennextjs/cloudflare、getCloudflareContext、キャッシュ階層、Workers 固有のエラー）。注：cloudflare-nextjs は Cloudflare における proxy.ts の例外を扱います（そこでは middleware.ts を使用してください）。
• Pages Router のパターン → このスキルが対象とするのは App Router のみです（Pages Router はレガシーです）
• 認証ライブラリ → clerk-auth、auth-js、または認証に特化した他のスキルを使用してください
• データベース統合 → cloudflare-d1、drizzle-orm-d1、またはデータベースに特化したスキルを使用してください
• UI コンポーネントライブラリ → Tailwind + shadcn/ui には tailwind-v4-shadcn スキルを使用してください
• 状態管理 → zustand-state-management、tanstack-query スキルを使用してください
• フォームライブラリ → react-hook-form-zod スキルを使用してください

---

Next.js 16 の破壊的変更

重要：Next.js 16 には複数の破壊的変更があります。詳細な移行手順については、references/next-16-migration-guide.md を参照してください。

破壊的変更	変更前	変更後
非同期 params	params.slug	const { slug } = await params
非同期ヘッダー	cookies() 同期	await cookies()
Middleware	middleware.ts	proxy.ts（名称変更）
並列ルート	default.js は任意	default.js 必須
キャッシュ	fetch を自動キャッシュ	"use cache" で明示的に有効化
revalidateTag()	引数 1 つ	引数 2 つ（tag + cacheLife）
Node.js	18.x+	20.9+ が必須
React	18.x	19.2+ が必須

非同期 params のクイック修正：

// ✅ Next.js 16 pattern
export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  return <div>{id}</div>
}

Codemod：bunx @next/codemod@canary upgrade latest

参照：例を含む完全な移行ガイドについては、references/next-16-migration-guide.md を参照してください。

---

Cache Components とキャッシュ API

"use cache" ディレクティブ（Next.js 16 の新機能）

'use cache'

export async function BlogPosts() {
  const posts = await db.posts.findMany()
  return posts.map(post => <article key={post.id}>{post.title}</article>)
}

キャッシュ API の概要

API	目的	例
"use cache"	コンポーネント／関数のキャッシュをオプトイン	'use cache' を先頭に記述
revalidateTag()	タグで無効化	revalidateTag('posts', 'max')
updateTag()	再検証せずにキャッシュを更新	updateTag('posts', newData)
refresh()	現在のページを更新	refresh()
revalidatePath()	パスで無効化	revalidatePath('/posts')

PPR（部分的なプリレンダリング）

// next.config.ts
const config = { experimental: { ppr: true } }

// page.tsx
export const experimental_ppr = true

export default function Page() {
  return (
    <>
      <StaticHeader />
      <Suspense fallback={<Skeleton />}>
        <DynamicContent />
      </Suspense>
    </>
  )
}

参照先：ISR、タグベースの再検証、高度なパターンを含むキャッシュ API の完全なリファレンスについては、references/caching-apis.md をご覧ください。

---

サーバーコンポーネント

App Router では、サーバーコンポーネントがデフォルトです。サーバー上で実行され、データの取得やデータベースへのアクセスができ、ロジックをサーバー側に保持できます。

// app/posts/page.tsx (Server Component by default)
export default async function PostsPage() {
  const posts = await db.posts.findMany()
  return <div>{posts.map(p => <article key={p.id}>{p.title}</article>)}</div>
}

Suspense によるストリーミング

import { Suspense } from 'react'

export default function Page() {
  return (
    <div>
      <Header />
      <Suspense fallback={<Skeleton />}>
        <Posts />
      </Suspense>
    </div>
  )
}

サーバーコンポーネントとクライアントコンポーネント

サーバーコンポーネント	クライアントコンポーネント
データ取得、DB アクセス	インタラクティブ性（onClick）
機密性の高いロジック	React フック（useState）
大きな依存関係	ブラウザー API
静的コンテンツ	リアルタイム更新

クライアントコンポーネント（'use client' が必要）：

'use client'
import { useState } from 'react'
export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

---

サーバーアクション

サーバーアクションは、サーバー上で実行され、クライアントコンポーネントまたはサーバーコンポーネントから呼び出せる非同期関数です。

基本的なサーバーアクション

// app/actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  await db.posts.create({ data: { title } })
  revalidatePath('/posts')
}

フォーム処理

// Server Component Form (simplest)
import { createPost } from './actions'

export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  )
}

利用可能なパターン

パターン	用途	参照先
ローディング表示付きクライアントフォーム	useFormState + useFormStatus	templates/server-action-form.tsx
エラー処理	{ error } または { success } を返す	references/server-actions-patterns.md
楽観的更新	useOptimistic フック	references/server-actions-patterns.md
ファイルアップロード	FormData + blob ストレージ	references/server-actions-patterns.md
アクション後のリダイレクト	redirect() 関数	references/server-actions-patterns.md

参照先：エラー処理、楽観的更新、ファイルアップロード、高度なパターンについては、references/server-actions-patterns.md をご覧ください。

---

ルートハンドラー

ルートハンドラーは、App Router における API Routes に相当します。

// app/api/posts/route.ts
export async function GET(request: Request) {
  const posts = await db.posts.findMany()
  return Response.json({ posts })
}

export async function POST(request: Request) {
  const body = await request.json()
  const post = await db.posts.create({ data: body })
  return Response.json({ post }, { status: 201 })
}

動的ルート（非同期 params を使用）：

// app/api/posts/[id]/route.ts
export async function GET(
  request: Request,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params // Await in Next.js 16
  const post = await db.posts.findUnique({ where: { id } })
  return post ? Response.json({ post }) : Response.json({ error: 'Not found' }, { status: 404 })
}

参照先：検索パラメーター、Webhook、ストリーミングのパターンについては、templates/route-handler-api.ts をご覧ください。

---

React 19.2 の機能

機能	使用方法
React Compiler	experimental: { reactCompiler: true } - 自動メモ化
View Transitions	useTransition() + router.push()
useEffectEvent	deps を指定せずに安定したイベントハンドラーを使用

---

メタデータ API

// Static metadata
export const metadata: Metadata = {
  title: 'My Blog',
  description: 'A blog about Next.js',
  openGraph: { title: 'My Blog', images: ['/og-image.jpg'] },
}

// Dynamic metadata (await params in Next.js 16)
export async function generateMetadata({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const post = await db.posts.findUnique({ where: { id } })
  return { title: post.title, description: post.excerpt }
}

---

画像とフォントの最適化

// next/image
import Image from 'next/image'
<Image src="/profile.jpg" alt="Profile" width={500} height={500} priority />

// next/font
import { Inter } from 'next/font/google'
const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
<html className={inter.variable}>

リモート画像：next.config.ts で images.remotePatterns を設定します。

---

重大なエラー上位 5 件

エラー 1：params は Promise です

エラー：Type 'Promise<{ id: string }>' is not assignable to type '{ id: string }'

解決策：Next.js 16 では params を await します：

export default async function Page({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
}

---

エラー 2：middleware.ts は非推奨です

警告：middleware.ts is deprecated. Use proxy.ts instead.

解決策：ファイル名と関数名を変更します：

// Rename: middleware.ts → proxy.ts
// Rename function: middleware → proxy
export function proxy(request: NextRequest) {
  // Same logic
}

---

エラー 3：並列ルートに default.js がありません

エラー：Parallel route @modal was matched but no default.js was found

解決策：default.tsx を追加します：

// app/@modal/default.tsx
export default function ModalDefault() {
  return null
}

---

エラー 4：サーバーコンポーネントでは React フックを使用できません

エラー：You're importing a component that needs useState. It only works in a Client Component

解決策：'use client' を追加します：

'use client'

import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

---

エラー 5：fetch() がキャッシュされません

原因：Next.js 16 では "use cache" によるオプトイン方式のキャッシュが使用されます。

解決策："use cache" ディレクティブを追加します：

'use cache'

export async function getPosts() {
  const response = await fetch('/api/posts')
  return response.json()
}

---

18 件のエラーすべてを参照：references/error-catalog.md

---

パフォーマンスパターン

パターン	用途
遅延読み込み	const HeavyComp = dynamic(() => import('./Heavy'), { ssr: false })
コード分割	ルートごとに自動で分割されます。各 page.tsx は独自のバンドルを取得します
Turbopack	Next.js 16 ではデフォルトです。--webpack フラグで無効にできます
PPR	experimental: { ppr: true } と <Suspense> 境界を使用します

---

TypeScript の設定

{
  "compilerOptions": {
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./*"] }
  }
}

---

リファレンスを読み込むタイミング

リファレンス	読み込むタイミング
next-16-migration-guide.md	Next.js 15 からの移行時、非同期パラメーターのエラー発生時、proxy.ts の設定時
server-actions-patterns.md	エラー処理、楽観的更新、ファイルのアップロード、高度なフォームを扱うとき
caching-apis.md	ISR、タグベースの再検証、updateTag()、refresh()、PPR の詳細を確認するとき
error-catalog.md	Next.js のエラーをデバッグするとき、包括的なエラー解決策を確認するとき
top-errors.md	最もよくある Next.js のエラー 5 件をすばやく修正するとき

---

同梱リソース

種類	ファイル
リファレンス	error-catalog.md、top-errors.md、next-16-migration-guide.md、server-actions-patterns.md、caching-apis.md
テンプレート	async-params-page.tsx、server-action-form.tsx、route-handler-api.ts、cache-component-use-cache.tsx、parallel-routes-with-default.tsx、proxy-migration.ts

---

関連スキル

スキル	目的
cloudflare-nextjs	OpenNext アダプター（@opennextjs/cloudflare）を介して Cloudflare Workers にデプロイします
tailwind-v4-shadcn	スタイリング
clerk-auth	認証
drizzle-orm-d1	データベース
react-hook-form-zod	フォーム
zustand-state-management	クライアントの状態管理

公式ドキュメント：https://nextjs.org/docs | App Router：https://nextjs.org/docs/app

---

バージョン：Next.js 16.2.0 | React 19.2.0 | Node.js 20.9+ | TypeScript 5.9+ 本番環境でのテスト済み：E コマース、SaaS、コンテンツサイト | トークン削減率：65-70%