nextjs-tanstack-form
/nextjs-tanstack-form
Use when building forms in Next.js 16 with TanStack Form v1 — Server Actions, Zod validation, multi-step wizards, field arrays.
- Author
- fusengine ↗
- Repository
- agents ↗
- Licence
- MIT
- Last repository change
- 12.10.2026
Assessment and security
- Files in this package
- 17
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when building forms in Next.js 16 with TanStack Form v1 — Server Actions, Zod validation, multi-step wizards, field arrays.
Original author description
Use when building forms in Next.js 16 with TanStack Form v1 — Server Actions, Zod validation, multi-step wizards, field arrays.
How it works
- Agent Workflow (MANDATORY)
- Overview
- Critical Rules
- SOLID Architecture
- Key Concepts
- Reference Guide
- Best Practices
- Comparison vs React Hook Form
SKILL.md preview
--- name: nextjs-tanstack-form description: Use when building forms in Next.js 16 with TanStack Form v1 — Server Actions, Zod validation, multi-step wizards, field arrays. versions: tanstack-form: 1.33 nextjs: 16 react: 19 zod: 4.6 user-invocable: true references: 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.md related-skills: nextjs-16, nextjs-shadcn, solid-nextjs --- <objective> 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. </objective> # 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](references/installation.md) | | Basic patterns | [basic-usage.md](references/basic-usage.md), [field-api.md](references/field-api.md) | | Validation | [validation-zod.md](references/validation-zod.md), [async-validation.md](references/async-validation.md) | | Server Actions | [server-actions.md](references/server-actions.md) | | Dynamic forms | [array-fields.md](references/array-fields.md), [multi-step-form.md](references/multi-step-form.md) | | UI integration | [shadcn-integration.md](references/shadcn-integration.md) | | TypeScript | [typescript.md](references/typescript.md) | | Migration | [migration-rhf.md](references/migration-rhf.md) | | Client-side form component | [client-form.md](references/client-form.md) — load when wiring `useActionState` + `mergeForm` in a `'use client'` form component | | Server-side validation | [server-validation.md](references/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 |
Files in this package (17)
- SKILL.md 6 KB
- references/array-fields.md 3 KB
- references/async-validation.md 3 KB
- references/basic-usage.md 5 KB
- references/client-form.md 3 KB
- references/field-api.md 3 KB
- references/form-state.md 3 KB
- references/installation.md 4 KB
- references/migration-rhf.md 2 KB
- references/multi-step-form.md 5 KB
- references/performance.md 2 KB
- references/server-actions.md 3 KB
- references/server-validation.md 2 KB
- references/shadcn-integration.md 4 KB
- references/testing.md 4 KB
- references/typescript.md 3 KB
- references/validation-zod.md 3 KB
Versions
The database has no other skills named nextjs-tanstack-form.
Database snapshot: 13.11.2026 · package version aec55070bfb7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90react-forms
Use when building type-safe forms in React with TanStack Form v1 — Zod/Yup/Valibot validation, async validation, field arrays. - 95form-validation-architect
End-to-end form handling with react-hook-form, Zod schemas, validation patterns, error messaging, field arrays, and multi-step wizards. Use for complex forms, validation architecture, autosave, field dependencies. Activate on "form validation", "react-hook-form", "Zod", "form… - 95react-hook-form-zod
Type-safe React forms with React Hook Form and Zod validation. Use for form schemas, field arrays, multi-step forms, or encountering validation errors, resolver issues, nested field problems. - 95forms
Forms knowledge base - react-hook-form, Zod validation, Server Actions, file upload, multi-step forms. Use when building forms, implementing validation, handling file uploads, or creating multi-step form flows. - 100react-forms
Form patterns for React: react-hook-form (most common), Formik (legacy/stable), TanStack Form (newer). Validation via zod / yup / valibot. Controlled vs uncontrolled inputs, field arrays, multi-step wizards. Use this skill to: - Wire react-hook-form with a validation schema. -… - 100react-hook-form
Build and modify forms that use React Hook Form or whose project conventions require it. Use when implementing controlled widgets, schema validation, fetched edit forms, conditional fields, multi-step wizards, field arrays, submission errors, or dirty-state handling. For review…