nextjs-tanstack-form

Original：🇺🇸 English

Translated

TanStack Form v1 for Next.js 16 with Server Actions, Zod validation, and shadcn/ui integration. Use when building forms, validation, multi-step wizards, or dynamic field arrays.

2installs

Sourcefusengine/agents

Added on2026-02-28

NPX Install

npx skill4agent add fusengine/agents nextjs-tanstack-form

SKILL.md Content

View Translation Comparison →

TanStack Form for Next.js 16

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

Agent Workflow (MANDATORY)

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

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

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