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:
- fuse-ai-pilot:explore-codebase - Analyze existing forms and validation patterns
- fuse-ai-pilot:research-expert - Verify latest TanStack Form docs via Context7/Exa
- 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 |
| Zod adapter |
Schema-first validation |
| Framework agnostic |
Same API for React, Vue, Solid |
| Headless |
Works with any UI library (shadcn/ui) |
Critical Rules
- formOptions shared - Define once, use in client and server
- Server validation - DB checks in
onServerValidate, not client
- Zod schemas - Client-side instant feedback
- useActionState - React 19 hook for Server Actions
- mergeForm - Combine server errors with client state
- 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 |
Max Lines |
form-options.ts |
Shared formOptions + Zod schema |
50 |
FormComponent.tsx |
Client form UI with fields |
80 |
form.action.ts |
Server Action with validation |
30 |
form.interface.ts |
Types for form values |
30 |
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
- Define schemas first - Zod schemas drive both validation and types
- Shared formOptions - Single source of truth for client/server
- Debounce async validation - Use
asyncDebounceMs for API calls
- form.Subscribe - Selective re-renders for submit state
- Field composition - Reusable field components with shadcn/ui
- 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 |
1---2name: nextjs-tanstack-form3description: Use when building forms in Next.js 16 with TanStack Form v1 — Server Actions, Zod validation, multi-step wizards, field arrays.4versions:5 tanstack-form: 1.06 nextjs: 167 react: 198 zod: 3.249user-invocable: true10references: references/installation.md, references/basic-usage.md, references/field-api.md, references/form-state.md, references/validation-zod.md, references/server-actions.md, references/array-fields.md, references/async-validation.md, references/shadcn-integration.md, references/typescript.md, references/multi-step-form.md, references/performance.md, references/testing.md, references/migration-rhf.md11related-skills: nextjs-16, nextjs-shadcn, solid-nextjs12metadata:13 source: https://skillmd.com/skills/fusengine/nextjs-tanstack-form14---1516<objective>17Implements 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.1819Covers 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.20</objective>2122# TanStack Form for Next.js 162324Type-safe, performant forms with Server Actions and signal-based reactivity.2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Analyze existing forms and validation patterns312. **fuse-ai-pilot:research-expert** - Verify latest TanStack Form docs via Context7/Exa323. **mcp__context7__query-docs** - Check form options and field API3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940### When to Use4142- Building forms with complex validation requirements43- Need Server Actions integration for form submission44- Implementing multi-step wizards or dynamic field arrays45- Require real-time async validation (username availability)46- Want type-safe forms with full TypeScript inference4748### Why TanStack Form4950| Feature | Benefit |51|---------|---------|52| Signal-based state | Minimal re-renders, optimal performance |53| Full TypeScript | DeepKeys, DeepValue inference |54| Server Actions native | Built-in Next.js 16 integration |55| Zod adapter | Schema-first validation |56| Framework agnostic | Same API for React, Vue, Solid |57| Headless | Works with any UI library (shadcn/ui) |5859---6061## Critical Rules62631. **formOptions shared** - Define once, use in client and server642. **Server validation** - DB checks in `onServerValidate`, not client653. **Zod schemas** - Client-side instant feedback664. **useActionState** - React 19 hook for Server Actions675. **mergeForm** - Combine server errors with client state686. **SOLID paths** - Forms in `modules/[feature]/src/components/forms/`6970---7172## SOLID Architecture7374### Module Structure7576Forms organized by feature module:7778- `modules/auth/src/components/forms/` - Auth forms (login, signup)79- `modules/auth/src/interfaces/` - Form types and schemas80- `modules/auth/src/actions/` - Server Actions for form submission81- `modules/cores/lib/forms/` - Shared form utilities8283### File Organization8485| File | Purpose | Max Lines |86|------|---------|-----------|87| `form-options.ts` | Shared formOptions + Zod schema | 50 |88| `FormComponent.tsx` | Client form UI with fields | 80 |89| `form.action.ts` | Server Action with validation | 30 |90| `form.interface.ts` | Types for form values | 30 |9192---9394## Key Concepts9596### Form Options Pattern9798Define form configuration once, share between client and server. Ensures type safety and consistency.99100### Field API101102Each field has state (value, errors, touched, validating) and handlers (handleChange, handleBlur).103104### Validation Levels105106- **onChange** - Real-time as user types107- **onBlur** - When field loses focus108- **onSubmit** - Before form submission109- **onServer** - Server-side in action110111### Error Management112113Errors exist at field-level and form-level. Use `field.state.meta.errors` for field errors, `form.state.errorMap` for form errors.114115---116117## Reference Guide118119| Need | Reference |120|------|-----------|121| Initial setup | [installation.md](references/installation.md) |122| Basic patterns | [basic-usage.md](references/basic-usage.md), [field-api.md](references/field-api.md) |123| Validation | [validation-zod.md](references/validation-zod.md), [async-validation.md](references/async-validation.md) |124| Server Actions | [server-actions.md](references/server-actions.md) |125| Dynamic forms | [array-fields.md](references/array-fields.md), [multi-step-form.md](references/multi-step-form.md) |126| UI integration | [shadcn-integration.md](references/shadcn-integration.md) |127| TypeScript | [typescript.md](references/typescript.md) |128| Migration | [migration-rhf.md](references/migration-rhf.md) |129| Client-side form component | [client-form.md](references/client-form.md) — load when wiring `useActionState` + `mergeForm` in a `'use client'` form component |130| Server-side validation | [server-validation.md](references/server-validation.md) — load when writing `createServerValidate` + `ServerValidateError` in a Server Action |131132---133134## Best Practices1351361. **Define schemas first** - Zod schemas drive both validation and types1372. **Shared formOptions** - Single source of truth for client/server1383. **Debounce async validation** - Use `asyncDebounceMs` for API calls1394. **form.Subscribe** - Selective re-renders for submit state1405. **Field composition** - Reusable field components with shadcn/ui1416. **Server errors merge** - Use `mergeForm` to show server validation errors142143---144145## Comparison vs React Hook Form146147| Aspect | TanStack Form | React Hook Form |148|--------|---------------|-----------------|149| Type Safety | 100% (DeepKeys) | Manual typing |150| Performance | Signals (minimal) | Refs (good) |151| Server Actions | Native support | Manual integration |152| Bundle Size | ~12KB | ~9KB |153| Learning Curve | Medium | Low |154| Use Case | Complex apps | Standard forms |