fix(form-core): infer form error types from onServerValidate in formOptions

.changeset/form-errors-on-server.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/form-core': patch
+---
+
+Infer form-level `errors` from `onServerValidate` specified in `formOptions`.

docs/framework/react/guides/ssr.md

@@ -200,6 +200,11 @@ export const formOpts = formOptions({
     firstName: '',
     age: 0,
   },
+  onServerValidate: ({ value }) => {
+    if (value.age < 12) {
+      return 'Server validation: You must be at least 12 to sign up'
+    }
+  },
 })
 ```
 
@@ -219,11 +224,6 @@ import { formOpts } from './shared-code'
 // Create the server action that will infer the types of the form from `formOpts`
 const serverValidate = createServerValidate({
   ...formOpts,
-  onServerValidate: ({ value }) => {
-    if (value.age < 12) {
-      return 'Server validation: You must be at least 12 to sign up'
-    }
-  },
 })
 
 export default async function someAction(prev: unknown, formData: FormData) {
@@ -278,7 +278,7 @@ export const ClientComp = () => {
   return (
     <form action={action as never} onSubmit={() => form.handleSubmit()}>
       {formErrors.map((error) => (
-        <p key={error as string}>{error}</p>
+        <p key={error}>{error}</p>
       ))}
 
       <form.Field

examples/react/next-server-actions/src/app/action.ts

@@ -8,11 +8,6 @@ import { formOpts } from './shared-code'
 
 const serverValidate = createServerValidate({
   ...formOpts,
-  onServerValidate: ({ value }) => {
-    if (value.age < 12) {
-      return 'Server validation: You must be at least 12 to sign up'
-    }
-  },
 })
 
 export default async function someAction(prev: unknown, formData: FormData) {

examples/react/next-server-actions/src/app/client-component.tsx

@@ -27,7 +27,7 @@ export const ClientComp = () => {
   return (
     <form action={action as never} onSubmit={() => form.handleSubmit()}>
       {formErrors.map((error) => (
-        <p key={error as unknown as string}>{error}</p>
+        <p key={error}>{error}</p>
       ))}
 
       <form.Field

examples/react/next-server-actions/src/app/shared-code.ts

@@ -5,4 +5,9 @@ export const formOpts = formOptions({
     firstName: '',
     age: 0,
   },
+  onServerValidate: ({ value }) => {
+    if (value.age < 12) {
+      return 'Server validation: You must be at least 12 to sign up'
+    }
+  },
 })

packages/form-core/src/FormApi.ts

@@ -510,6 +510,12 @@ export interface FormOptions<
     TOnDynamic,
     TOnDynamicAsync
   >
+  /**
+   * Server-only validator used by `createServerValidate`. Specify it in shared
+   * `formOptions` so the client form infers `state.errors` / `errorMap.onServer`
+   * from the same function. This is not executed in the browser.
+   */
+  onServerValidate?: TOnServer
 
   validationLogic?: ValidationLogicFn
 

packages/form-core/tests/formOptions.test-d.ts

@@ -319,4 +319,33 @@ describe('formOptions', () => {
       ('Too short!' | 'I just need an error')[]
     >()
   })
+
+  it('should infer form error types from onServerValidate in formOptions', () => {
+    const formOpts = formOptions({
+      defaultValues: {
+        firstName: '',
+        age: 0,
+      },
+      onServerValidate: ({ value }) => {
+        expectTypeOf(value.age).toEqualTypeOf<number>()
+        if (value.age < 12) {
+          return 'Server validation: You must be at least 12 to sign up' as const
+        }
+        return undefined
+      },
+    })
+
+    const form = new FormApi(formOpts)
+    expectTypeOf(form.state.errors).toEqualTypeOf<
+      'Server validation: You must be at least 12 to sign up'[]
+    >()
+    expectTypeOf(form.state.errorMap.onServer).toEqualTypeOf<
+      'Server validation: You must be at least 12 to sign up' | undefined
+    >()
+
+    const form2 = new FormApi({ ...formOpts })
+    expectTypeOf(form2.state.errors).toEqualTypeOf<
+      'Server validation: You must be at least 12 to sign up'[]
+    >()
+  })
 })

packages/react-form/tests/useForm.test-d.tsx

@@ -154,4 +154,26 @@ describe('useForm', () => {
 
     expectTypeOf(form.state.values).toExtend<PersonWithAge>()
   })
+
+  it('should infer form error types from onServerValidate in formOptions', () => {
+    const formOpts = formOptions({
+      defaultValues: {
+        firstName: '',
+        age: 0,
+      },
+      onServerValidate: ({ value }) => {
+        expectTypeOf(value.age).toEqualTypeOf<number>()
+        if (value.age < 12) {
+          return 'Server validation: You must be at least 12 to sign up' as const
+        }
+        return undefined
+      },
+    })
+
+    const form = useForm({ ...formOpts })
+
+    expectTypeOf(form.state.errors).toEqualTypeOf<
+      'Server validation: You must be at least 12 to sign up'[]
+    >()
+  })
 })