Next.js プロダクション運用

Next.js 16 App Router アプリのコードに使用します。セキュリティ固有のルール（アクション内の認証、CSP、ヘッダー、taint）は nextjs-security に、コンテナのルールは docker-nextjs にあります。Claude Code のビルトイン next-best-practices スキルはファイル規則、メタデータ、画像・フォント最適化を詳細にカバーしています。このスキルでは、Nuvraxis での構築・出荷方法に固有のルールのみを追加します。

基準: Next 16.4、React 19.3、Turbopack（dev および build のデフォルト）、cacheComponents: true（partialPrefetching: true 付き）、output: "standalone"、typedRoutes: true。テンプレートの next.config.ts が信頼できる情報源です。

ルール

サーバーコンポーネントをデフォルトとし、"use client" は状態、エフェクト、ブラウザAPI、またはイベントハンドラが必要な場合のみ使用する。 ディレクティブは、それが本当に必要な最小のリーフに配置します。ファイルが nuvui をインポートしているからといって追加してはいけません。nuvui のステートフルな部分は独自のディレクティブを持っています（nuvui スキール、rules/server-components.md を参照）。
```
// 誤り: 1つのハンドラのためにページ全体がクライアントになる
"use client";
export default function Page() { … <Select onValueChange={…} /> … }

// 正しい: ページはサーバーに残り、ハンドラはリーフにある
export default async function Page() {
  const people = await getPeople();
  return <PeopleFilter people={people} />; // people-filter.tsx に "use client" がある
}
```
クライアントコンポーネントに渡すプロパティはシリアライズ可能でなければなりません。関数（Server Actions を除く）やクラスインスタンスは許可されません。
データを必要とするコンポーネント内で、サーバーサイドでフェッチする。 useEffect によるフェッチや、単に自分のページにデータを供給するためのルートハンドラは使用しません。リクエストごとの重複排除には React の cache() を使用し、リクエスト間のキャッシュにはルール3を使用します。
"use cache" + cacheLife + cacheTag でキャッシュする。それ以外はすべて動的とする。 キャッシュコンポーネントでは、明示的に指定しない限り何もキャッシュされず、fetch に暗黙のキャッシュはありません。
```
import { cacheLife, cacheTag } from "next/cache";

export async function getInvoice(id: InvoiceId) {
  "use cache";
  cacheLife("minutes");
  cacheTag(`invoice:${id}`);
  return db.invoice.findUnique({ where: { id } });
}
```
古いセグメント設定（export const dynamic、revalidate、fetchCache）は使用しないでください。キャッシュコンポーネントではエラーになります。引数とクロージャでキャプチャされた値がキャッシュキーの一部となるため、リクエストオブジェクト全体ではなく ID を渡します。詳細、プロファイル、および "use cache: private" については、references/caching.md を参照してください。
Server Actions 内では updateTag で、それ以外では revalidateTag(tag, "max") で無効化する。 updateTag(tag) は「読み取り後書き込み」の整合性を提供し、Server Actions 内でのみ動作します。Webhook やルートハンドラからは revalidateTag(tag, "max")（stale-while-revalidate）または revalidateTag(tag, { expire: 0 }) を使用します。1引数の revalidateTag(tag) は非推奨です。
リクエスト時にしか確定しないデータは <Suspense> でラップする。そうしないとビルドが失敗する。 cookies()、headers()、searchParams、connection()、およびキャッシュされていない I/O を Suspense 境界外で使用すると、「プリレンダリング中にキャッシュされていないデータまたはランタイムデータ」というエラーでプリレンダリングが停止します。スケルトンフォールバック付きの境界を設定するか、キャッシュするか、または（ルートレイアウトのみ。ルール14を参照）export const instant = false でルートをブロッキングにマークします。params、searchParams、cookies()、headers() はすべて非同期です。await してください。

すべての Server Action は、自身で入力の検証と認可のチェックを行う。 Server Action は、どのページに書かれていても公開 POST エンドポイントです。FormData は typescript-production（valibot）のスキーマでパースし、認可し、ミューテーションし、updateTag します。期待される失敗には型付きの結果を返し、バグの場合のみスローします。完全なルールセットは nextjs-security にあります。

"use server";
export async function renameProject(_: State, form: FormData): Promise<State> {
  const session = await requireSession();                  // 不在時は 401
  const input = v.safeParse(RenameProject, Object.fromEntries(form));
  if (!input.success) return { ok: false, errors: flatten(input.issues) };
  await assertCanEdit(session, input.output.projectId);    // 許可されていない場合は 403
  await db.project.update(…);
  updateTag(`project:${input.output.projectId}`);
  return { ok: true };
}

ルートハンドラは、他のクライアント（Webhook、モバイル、ヘルスチェック）向けであり、自分のページ向けではない。 app/api/ 配下に配置します。アクションと同様にボディを検証し、Response.json(...) を返し、ステータスコードを意図的に設定します。
すべてのアプリに動的で依存関係のない GET /api/health を設置する。 Docker の HEALTHCHECK と Kubernetes のプローブがこれを叩きます。データベースにアクセスせずに応答する必要があるため、遅い依存関係があってもすべての Pod が再起動されることはありません。await connection() により、静的ファイルとしてプリレンダリングされることを防ぎます。テンプレートの src/app/api/health/route.ts にあり、proxy.ts は /api/health をマッチャーから除外します。
ルートレベル、および UX が異なるセグメントごとに error.tsx、loading.tsx、not-found.tsx を配置する。 error.tsx はクライアントコンポーネントです。instrumentation.ts の onRequestError でログ出力し、reset でリトライできるように表示します。エラーメッセージは絶対に表示しません。空の状態をレンダリングする代わりに、レコードが見つからない場合は notFound() を呼び出します。
NEXT_PUBLIC_* はビルド時に埋め込まれ、それ以外はランタイムにサーバー上で読み込まれる。 1つのイメージが変更されずに main からプロダクションに昇格するため、NEXT_PUBLIC_ の値はすべての環境で同じです。ビルド時の定数（アプリ名、すべての環境で同じパブリック Sentry DSN）のみをそこに配置します。環境ごとの設定（API URL、フィーチャーフラグ、シークレット）はサーバーサイドの process.env.X であり、サーバーコンポーネントまたはアクション内で読み取り、必要に応じてプロパティとしてクライアントに渡します。環境変数は src/env.ts（valibot）で1回検証し、そこからインポートします。next.config.ts の env キーは使用しないでください。クライアントバンドルにインライン化されます。
サーバー専用モジュールには import "server-only" を記述する。 シークレットを読み取るもの、データベースにアクセスするもの、認証情報を持つ SDK をインポートするものなど。クライアントがこれをインポートすると、情報漏洩ではなくビルドエラーになります。
after() はレスポンスを遅らせるべきでない処理（監査ログ、分析、キャッシュウォームアップ）に使用する。 after を呼び出す前に cookies()/headers() を読み取り、after 内では読み取りません。同じプロセス内で実行されるため、Pod は SIGTERM の猶予期間を必要とします（チャートで terminationGracePeriodSeconds を設定）。
src/instrumentation.ts で registerOTel + onRequestError によりインストルメンテーションを行う。 @vercel/otel による OpenTelemetry、エクスポーターはランタイムの標準 OTEL_EXPORTER_OTLP_* 環境変数で設定します。references/observability.md を参照してください。
output: "standalone" を維持し、ワークスペースの外部からインポートしない。 Docker ランナーは .next/standalone、.next/static、public のみをコピーします。モノレポでは、server.js は .next/standalone/apps/<app>/server.js に配置されます。ワークスペースルートは pnpm-lock.yaml から検出されるため、ビルドが警告しない限り outputFileTracingRoot や turbopack.root は設定しないでください。セルフホスティングの詳細（マルチレプリカ、Server Action キー、deploymentId）については、references/self-hosting.md を参照してください。
ルートレイアウトは CSP nonce を読み取るため、アプリはリクエストごとにレンダリングされる。 テンプレートの proxy.ts は nonce ベースの CSP を設定し、src/app/layout.tsx には export const instant = false があります。これは意図的なトレードオフです。nonce とプリレンダリングされた静的シェルは共存できず、ログイン済みのビジネスアプリでは厳格な CSP が優先されます。"use cache" によるデータキャッシュは引き続き機能します。nextjs-security のルール4を読まずにこれらのいずれかを削除しないでください。
スタイル: グローバル BEM SCSS、コンポーネントがインポートする。 Turbopack は sass パッケージで Sass をコンパイルします。sassOptions.loadPaths: ["src/styles"] により、任意の深さから @use "abstracts" が機能します。~ インポートや sassOptions.functions は使用しません。ルールは scss-bem にあります。
画像は next/image、フォントは next/font を使用する。 sharp は最適化のために Next に同梱されています。ランナーイメージに追加のパッケージは必要ありません。リモート画像には、正確なホスト名を指定した images.remotePatterns が必要です。
pnpm next analyze でバンドルサイズをチェックする（Turbopack のアナライザー。@next/bundle-analyzer は webpack 専用）。重いクライアントウィジェット（nuvui エディター、マップ、スクロールしないと見えないチャート）は next/dynamic で遅延読み込みします。
型付きルートと生成された型を使用する。 typedRoutes: true は <Link href> をチェックします。PageProps<"/invoices/[id]"> と LayoutProps は、next typegen（next dev/next build で自動実行）の後にグローバルになります。params の型を手書きしないでください。
next lint は使用しない。 16 で削除されました。Biome がリンターとして機能します（biome を参照）。TypeScript はパッケージごとに tsc --noEmit でチェックします。

確認

pnpm typecheck
pnpm lint
pnpm build                      # turbo run build: プリレンダリングエラー、型エラー、Sass エラーで失敗
pnpm --filter <app> start &     # その後:
curl -fsS localhost:3000/api/health

Nuvraxis/nuvraxis-plugins

nuvraxis-plugins とは？

お気に入りのAIに質問する

ドキュメント

Next.js プロダクション運用

ルール

確認

ソース

Individual skills in this repo