nextjs-tanstack-form

Implements TanStack Form v1 in Next.js 16 with native Server Actions integration: shared `formOptions` (single source of truth for client and server), Zod schemas for both instant client feedback and `onServerValidate` database checks, `useActionState` for the React 19 form-submission hook, and `mergeForm` to combine server-returned errors with client state.

Covers the Field API (state + handlers), validation timing (onChange/onBlur/onSubmit/onServer), dynamic field arrays and multi-step wizards, debounced async validation, and shadcn/ui field composition. Also documents SOLID file organization for forms (form-options.ts, FormComponent.tsx, form.action.ts) and a comparison against React Hook Form. This is the Next.js Server Actions variant of TanStack Form — for a plain React app without Next.js see the react-forms skill.

TanStack Form for Next.js 16

Type-safe, performant forms with Server Actions and signal-based reactivity.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing forms and validation patterns
2. fuse-ai-pilot:research-expert - Verify latest TanStack Form docs via Context7/Exa
3. mcp__context7__query-docs - Check form options and field API

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

When to Use

• Building forms with complex validation requirements
• Need Server Actions integration for form submission
• Implementing multi-step wizards or dynamic field arrays
• Require real-time async validation (username availability)
• Want type-safe forms with full TypeScript inference

Why TanStack Form

Feature	Benefit
Signal-based state	Minimal re-renders, optimal performance
Full TypeScript	DeepKeys, DeepValue inference
Server Actions native	Built-in Next.js 16 integration
Standard Schema (Zod, Valibot…)	Schema-first validation, no adapter needed
Framework agnostic	Same API for React, Vue, Solid
Headless	Works with any UI library (shadcn/ui)

---

Critical Rules

1. formOptions shared - Define once, use in client and server
2. Server validation - DB checks in onServerValidate, not client
3. Zod schemas - Client-side instant feedback
4. useActionState - React 19 hook for Server Actions
5. mergeForm - Combine server errors with client state
6. SOLID paths - Forms in modules/[feature]/src/components/forms/

---

SOLID Architecture

Module Structure

Forms organized by feature module:

• modules/auth/src/components/forms/ - Auth forms (login, signup)
• modules/auth/src/interfaces/ - Form types and schemas
• modules/auth/src/actions/ - Server Actions for form submission
• modules/cores/lib/forms/ - Shared form utilities

File Organization

File	Purpose
form-options.ts	Shared formOptions + Zod schema
FormComponent.tsx	Client form UI with fields
form.action.ts	Server Action with validation
form.interface.ts	Types for form values

---

Key Concepts

Form Options Pattern

Define form configuration once, share between client and server. Ensures type safety and consistency.

Field API

Each field has state (value, errors, touched, validating) and handlers (handleChange, handleBlur).

Validation Levels

• onChange - Real-time as user types
• onBlur - When field loses focus
• onSubmit - Before form submission
• onServer - Server-side in action

Error Management

Errors exist at field-level and form-level. Use field.state.meta.errors for field errors, form.state.errorMap for form errors.

---

Reference Guide

Need	Reference
Initial setup	installation.md
Basic patterns	basic-usage.md, field-api.md
Validation	validation-zod.md, async-validation.md
Server Actions	server-actions.md
Dynamic forms	array-fields.md, multi-step-form.md
UI integration	shadcn-integration.md
TypeScript	typescript.md
Migration	migration-rhf.md
Client-side form component	client-form.md — load when wiring useActionState + mergeForm in a 'use client' form component
Server-side validation	server-validation.md — load when writing createServerValidate + ServerValidateError in a Server Action

---

Best Practices

1. Define schemas first - Zod schemas drive both validation and types
2. Shared formOptions - Single source of truth for client/server
3. Debounce async validation - Use asyncDebounceMs for API calls
4. form.Subscribe - Selective re-renders for submit state
5. Field composition - Reusable field components with shadcn/ui
6. Server errors merge - Use mergeForm to show server validation errors

---

Comparison vs React Hook Form

Aspect	TanStack Form	React Hook Form
Type Safety	100% (DeepKeys)	Manual typing
Performance	Signals (minimal)	Refs (good)
Server Actions	Native support	Manual integration
Bundle Size	~12KB	~9KB
Learning Curve	Medium	Low
Use Case	Complex apps	Standard forms