nextjs-tanstack-form_skill

Overview

This skill provides a TanStack Form v1 integration for Next.js 16 with Server Actions, Zod validation, and shadcn/ui support. It delivers type-safe, signal-based forms optimized for minimal re-renders and full TypeScript inference. Use it to build validated single-step or multi-step forms, dynamic arrays, and server-validated workflows.

How this skill works

Before implementation, spawn three agents (explore-codebase, research-expert, query-docs) to analyze existing patterns and verify TanStack Form options and APIs. The formOptions pattern defines configuration once and is shared between client and server to preserve types. Client uses signal-based form state and Zod for instant feedback; Server Actions handle server-side validation and DB checks with mergeForm to combine server errors into the client state. After implementation, run the validation agent (sniper).

When to use it

• Building complex forms with deep TypeScript types and schema-driven validation
• Implementing Server Actions for secure server-side validation and submission
• Creating multi-step wizards or dynamic field arrays
• Performing real-time async checks (username/email availability) with debounce
• Integrating headless form logic with shadcn/ui or custom UI components

Best practices

• Define Zod schemas first and use them to derive form types and validation
• Keep a single shared formOptions file used by client and server to ensure consistency
• Run async validation with debounce (asyncDebounceMs) and perform DB checks in onServerValidate
• Use form.Subscribe/selectors to minimize re-renders and subscribe only to needed state
• Compose reusable field components with shadcn/ui and expose field handlers and meta
• Merge server-side errors with mergeForm so users see combined feedback

Example use cases

• Signup flow with client-side Zod checks and server-side email uniqueness validation
• Multi-step checkout or onboarding wizard with persisted Server Actions between steps
• Admin UI with dynamic permission arrays and add/remove field controls
• Real-time username availability check via async validation and debounce
• Migration from React Hook Form to a type-safe signal-based pattern for complex apps