Skip to content
Skills Library
Programming · Building & coding

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.

Repository
agents ↗
Licence
MIT
Last repository change
12.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
17
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.10.2026, without references to retired models or APIs.

Licence

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

  1. Agent Workflow (MANDATORY)
  2. Overview
  3. Critical Rules
  4. SOLID Architecture
  5. Key Concepts
  6. Reference Guide
  7. Best Practices
  8. Comparison vs React Hook Form
Original SKILL.md headings · 141 lines, 753 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.