nextjs-tanstack-form

# TanStack Form for Next.js 16

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

## Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

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 |
| Zod adapter | Schema-first validation |
| 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 | Max Lines