nextjs-tanstack-form

TanStack Form v1 を Next.js 16 に実装し、ネイティブの Server Actions との統合を実現します。共有 `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 との比較も記載しています。これは Next.js Server Actions 版の TanStack Form です。Next.js を使わない通常の React アプリについては、react-forms スキルを参照してください。

Next.js 16 向け TanStack Form

Server Actions とシグナルベースのリアクティビティを備えた、型安全で高パフォーマンスなフォームです。

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

実装の前に、必ず 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 を実行します。

---

概要

使用する場面

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

TanStack Form を選ぶ理由

特徴	メリット
シグナルベースの状態管理	再レンダリングを最小限に抑え、パフォーマンスを最適化
TypeScript の完全サポート	DeepKeys、DeepValue の推論
Server Actions にネイティブ対応	Next.js 16 との統合を標準搭載
Standard Schema（Zod、Valibot…）	スキーマ優先のバリデーションで、アダプター不要
フレームワーク非依存	React、Vue、Solid で同じ API を使用
ヘッドレス	あらゆる UI ライブラリ（shadcn/ui）で動作

---

重要なルール

1. formOptions を共有 - 一度定義し、クライアントとサーバーの両方で使用します
2. サーバー側のバリデーション - DB チェックはクライアントではなく onServerValidate で行います
3. Zod スキーマ - クライアント側で即時フィードバックを提供します
4. useActionState - Server Actions 用の 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/ - フォーム送信用の Server Actions
• modules/cores/lib/forms/ - 共有フォームユーティリティ

ファイル構成

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

---

主な概念

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

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

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
学習曲線	中程度	低い
用途	複雑なアプリ	標準的なフォーム