nextjs-tanstack-form

Next.js 16 で TanStack Form v1 を実装し、ネイティブのサーバーアクション統合に対応します。共有 `formOptions`（クライアントとサーバーの単一の信頼できる情報源）、クライアントでの即時フィードバックと `onServerValidate` によるデータベースチェックの両方に対応する Zod スキーマ、React 19 のフォーム送信フックとしての `useActionState`、サーバーから返されたエラーをクライアントの状態と結合する `mergeForm` を使用します。

Field API（状態とハンドラー）、バリデーションのタイミング（onChange／onBlur／onSubmit／onServer）、動的なフィールド配列とマルチステップウィザード、デバウンス付き非同期バリデーション、shadcn/ui のフィールド構成についても説明します。また、フォームの SOLID なファイル構成（form-options.ts、FormComponent.tsx、form.action.ts）と React Hook Form との比較も記載します。これは TanStack Form の Next.js サーバーアクション版です。Next.js を使わない通常の React アプリについては、react-forms スキルを参照してください。

Next.js 16 向け TanStack Form

サーバーアクションとシグナルベースのリアクティビティに対応した、型安全で高性能なフォームです。

エージェントのワークフロー（必須）

実装を始める前に、以下の 3 つのエージェントを並行して起動してください。それぞれ name を指定して Agent を 1 回ずつ呼び出します。

1. fuse-ai-pilot:explore-codebase - 既存のフォームとバリデーションのパターンを分析します
2. fuse-ai-pilot:research-expert - Context7／Exa を使用して、最新の TanStack Form ドキュメントを確認します
3. mcp__context7__query-docs - フォームオプションと Field API を確認します

実装後、検証のために fuse-ai-pilot:sniper を実行します。

---

概要

使用する場面

• 複雑なバリデーション要件を持つフォームを構築する場合
• フォーム送信にサーバーアクション統合が必要な場合
• マルチステップウィザードや動的なフィールド配列を実装する場合
• リアルタイムの非同期バリデーション（ユーザー名の利用可否など）が必要な場合
• TypeScript による完全な型推論を備えた型安全なフォームが必要な場合

TanStack Form を選ぶ理由

機能	メリット
シグナルベースの状態	再レンダリングを最小限に抑え、パフォーマンスを最適化します
完全な TypeScript 対応	DeepKeys、DeepValue の推論
サーバーアクションにネイティブ対応	Next.js 16 統合を内蔵しています
Standard Schema（Zod、Valibot など）	スキーマを中心としたバリデーションで、アダプターは不要です
フレームワーク非依存	React、Vue、Solid で同じ API を使用できます
ヘッドレス	任意の UI ライブラリ（shadcn/ui）で動作します

---

重要なルール

1. formOptions を共有 - 一度定義し、クライアントとサーバーで使用します
2. サーバー側のバリデーション - DB チェックはクライアントではなく onServerValidate で行います
3. Zod スキーマ - クライアント側で即時フィードバックを提供します
4. useActionState - サーバーアクション用の React 19 フックです
5. mergeForm - サーバーエラーをクライアントの状態と結合します
6. SOLID なパス - フォームは modules/[feature]/src/components/forms/ に配置します

---

SOLID アーキテクチャ

モジュール構成

フォームは機能モジュールごとに整理します。

• modules/auth/src/components/forms/ - 認証フォーム（ログイン、サインアップ）
• modules/auth/src/interfaces/ - フォームの型とスキーマ
• modules/auth/src/actions/ - フォーム送信用のサーバーアクション
• modules/cores/lib/forms/ - 共有フォームユーティリティ

ファイル構成

ファイル	用途
form-options.ts	共有の formOptions と Zod スキーマ
FormComponent.tsx	フィールドを含むクライアントフォーム UI
form.action.ts	バリデーションを行うサーバーアクション
form.interface.ts	フォーム値の型

---

主な概念

フォームオプションパターン

フォームの設定を一度だけ定義し、クライアントとサーバーで共有します。これにより、型安全性と一貫性を確保できます。

Field API

各フィールドには状態（値、エラー、操作済み、バリデーション中）とハンドラー（handleChange、handleBlur）があります。

バリデーションの段階

• onChange - ユーザーの入力に応じてリアルタイムに実行します
• onBlur - フィールドがフォーカスを失ったときに実行します
• onSubmit - フォーム送信前に実行します
• onServer - アクション内でサーバー側のバリデーションを実行します

エラー管理

エラーはフィールドレベルとフォームレベルに存在します。フィールドのエラーには field.state.meta.errors、フォームのエラーには form.state.errorMap を使用します。

---

リファレンスガイド

必要な情報	リファレンス
初期設定	installation.md
基本パターン	basic-usage.md、field-api.md
バリデーション	validation-zod.md、async-validation.md
Server Actions	server-actions.md
動的フォーム	array-fields.md、multi-step-form.md
UI 統合	shadcn-integration.md
TypeScript	typescript.md
移行	migration-rhf.md
クライアント側フォームコンポーネント	client-form.md — 'use client' フォームコンポーネントで useActionState と mergeForm を組み合わせる場合に読み込んでください
サーバー側バリデーション	server-validation.md — Server Action で createServerValidate と ServerValidateError を記述する場合に読み込んでください

---

ベストプラクティス

1. 最初にスキーマを定義する - Zod スキーマがバリデーションと型の両方を担います
2. formOptions を共有する - クライアントとサーバーの信頼できる唯一の情報源にします
3. 非同期バリデーションをデバウンスする - API 呼び出しには asyncDebounceMs を使用します
4. form.Subscribe - 送信状態に応じた選択的な再レンダリングを行います
5. フィールドを組み合わせる - shadcn/ui で再利用可能なフィールドコンポーネントを作成します
6. サーバーエラーをマージする - mergeForm を使用してサーバーのバリデーションエラーを表示します

---

React Hook Form との比較

項目	TanStack Form	React Hook Form
型安全性	100%（DeepKeys）	手動で型を指定
パフォーマンス	シグナル（最小限）	Refs（良好）
Server Actions	ネイティブサポート	手動で統合
バンドルサイズ	約12KB	約9KB
学習曲線	中程度	低い
用途	複雑なアプリ	標準的なフォーム