mcpField
N
nextjs-tanstack-form

nextjs-tanstack-form

github.com/fusengine开发3444 次安装1 天前更新
代码仓库

关于 nextjs-tanstack-form

面向 Next.js 16 项目的 TanStack Form v1 开发参考，适用于需要复杂校验和服务端提交的表单。涵盖 Server Actions、共享配置及客户端与服务端错误合并。

主要功能

  1. 01集成 Next.js 16 Server Actions
  2. 02客户端与服务端共享 formOptions
  3. 03Zod 即时校验与数据库校验
  4. 04支持动态字段数组和多步向导
  5. 05合并服务端错误与客户端状态

适用场景

  1. 01构建复杂校验表单
  2. 02实现多步表单流程
  3. 03异步校验用户名可用性

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/fusengine/claude-plugins --skill nextjs-tanstack-form

安装后在 Claude Code 中输入/nextjs-tanstack-form确认已加载。

详细介绍

在 Next.js 16 中实现 TanStack Form v1，并原生集成 Server Actions：共享 `formOptions`（客户端和服务端的唯一事实来源）、使用 Zod schema 提供即时客户端反馈并通过 `onServerValidate` 执行数据库检查、使用 `useActionState` 作为 React 19 的表单提交 Hook，并使用 `mergeForm` 将服务端返回的错误与客户端状态合并。

涵盖 Field API（状态 + 处理器）、验证时机（onChange/onBlur/onSubmit/onServer）、动态字段数组和多步骤向导、带防抖的异步验证，以及 shadcn/ui 字段组合。还会介绍表单的 SOLID 文件组织方式（form-options.ts、FormComponent.tsx、form.action.ts），并与 React Hook Form 进行比较。这是 TanStack Form 的 Next.js Server Actions 版本；如需不使用 Next.js 的纯 React 应用，请参阅 react-forms skill。

TanStack Form for Next.js 16

借助 Server Actions 和基于信号的响应性，构建类型安全、高性能的表单。

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个使用一次 Agent 调用，并设置 name：

  1. fuse-ai-pilot:explore-codebase - 分析现有表单和验证模式
  2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 TanStack Form 文档
  3. mcp__context7__query-docs - 检查 form options 和 field API

实现后，运行 fuse-ai-pilot:sniper 进行验证。

概述

适用场景
  • 构建具有复杂验证需求的表单
  • 需要集成 Server Actions 来提交表单
  • 实现多步骤向导或动态字段数组
  • 需要实时异步验证（用户名是否可用）
  • 希望表单具备类型安全性和完整的 TypeScript 类型推断
为什么选择 TanStack Form
功能优势
基于信号的状态最大限度减少重新渲染，性能最优
完整的 TypeScript 支持DeepKeys、DeepValue 类型推断
原生支持 Server Actions内置 Next.js 16 集成
Standard Schema（Zod、Valibot…）以 schema 为先进行验证，无需适配器
与框架无关React、Vue、Solid 使用相同 API
无头设计适用于任何 UI 库（shadcn/ui）

关键规则

  1. 共享 formOptions - 定义一次，在客户端和服务端使用
  2. 服务端验证 - 在 onServerValidate 中执行数据库检查，而不是在客户端
  3. Zod schema - 提供即时客户端反馈
  4. useActionState - 用于 Server Actions 的 React 19 Hook
  5. mergeForm - 将服务端错误与客户端状态合并
  6. SOLID 路径 - 表单位于 modules/[feature]/src/components/forms/

SOLID 架构

模块结构

按功能模块组织表单：

  • modules/auth/src/components/forms/ - 身份验证表单（登录、注册）
  • modules/auth/src/interfaces/ - 表单类型和 schema
  • modules/auth/src/actions/ - 用于提交表单的 Server Actions
  • modules/cores/lib/forms/ - 共享表单工具
文件组织
文件用途
form-options.ts共享的 formOptions + Zod schema
FormComponent.tsx带字段的客户端表单 UI
form.action.ts带验证的 Server Action
form.interface.ts表单值类型

核心概念

Form Options 模式

只定义一次表单配置，并在客户端和服务端共享，确保类型安全与一致性。

Field API

每个字段都有状态（值、错误、已触碰、正在验证）和处理器（handleChange、handleBlur）。

验证级别
  • onChange - 用户输入时实时验证
  • onBlur - 字段失去焦点时验证
  • onSubmit - 提交表单前验证
  • onServer - 在 action 中进行服务端验证
错误管理

错误分为字段级和表单级。字段错误使用 field.state.meta.errors，表单错误使用 form.state.errorMap。

参考指南

需求参考资料
初始设置installation.md
基本模式basic-usage.md、field-api.md
验证validation-zod.md、async-validation.md
Server Actionsserver-actions.md
动态表单array-fields.md、multi-step-form.md
UI 集成shadcn-integration.md
TypeScripttypescript.md
迁移migration-rhf.md
客户端表单组件client-form.md — 在 'use client' 表单组件中接入 useActionState + mergeForm 时加载
服务端验证server-validation.md — 在 Server Action 中编写 createServerValidate + ServerValidateError 时加载

最佳实践

  1. 先定义 schema - Zod schema 同时驱动验证和类型
  2. 共享 formOptions - 客户端和服务端的唯一事实来源
  3. 对异步验证进行防抖 - 对 API 调用使用 asyncDebounceMs
  4. form.Subscribe - 有选择地重新渲染提交状态
  5. 字段组合 - 使用 shadcn/ui 构建可复用的字段组件
  6. 合并服务端错误 - 使用 mergeForm 显示服务端验证错误

与 React Hook Form 对比

方面TanStack FormReact Hook Form
类型安全100%（DeepKeys）手动声明类型
性能Signals（开销极低）Refs（良好）
Server Actions原生支持手动集成
包体积~12KB~9KB
学习曲线中等低
使用场景复杂应用标准表单

评论

支持 Markdown