mcpField
N
nextjs-tanstack-form

nextjs-tanstack-form

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

关于 nextjs-tanstack-form

nextjs-tanstack-form 是面向 Next.js 16 项目的 TanStack Form 实践指南，适用于构建复杂且具备类型安全的表单。它说明如何结合 Server Actions、共享配置和客户端与服务端验证，并涵盖动态字段及多步表单。

主要功能

  1. 01通过共享 formOptions 统一客户端与服务端配置
  2. 02结合 Zod 和 Server Actions 验证
  3. 03使用 mergeForm 合并服务端错误
  4. 04支持动态字段数组与多步表单
  5. 05涵盖异步验证和 shadcn/ui 字段组合

适用场景

  1. 01在 Next.js 16 中构建 Server Actions 表单
  2. 02实现客户端即时反馈和服务端数据库校验
  3. 03开发动态字段表单或多步向导
  4. 04集成防抖异步验证与可复用字段

安装

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

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

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
array-fields.md
async-validation.md
basic-usage.md
client-form.md
field-api.md
form-state.md
installation.md
migration-rhf.md
multi-step-form.md
performance.md
server-actions.md
server-validation.md
shadcn-integration.md
testing.md
typescript.md
validation-zod.md

详细介绍

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

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

Next.js 16 中的 TanStack Form

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

Agent 工作流（强制）

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

  1. fuse-ai-pilot:explore-codebase - 分析现有表单和验证模式
  2. fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 TanStack Form 文档
  3. mcp__context7__query-docs - 检查表单选项和 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 schemas - 提供即时客户端反馈
  4. useActionState - 用于 Server Actions 的 React 19 钩子
  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 schema50
FormComponent.tsx带字段的客户端表单 UI80
form.action.ts带验证的 Server Action30
form.interface.ts表单值的类型30

核心概念

表单选项模式

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

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