v2: public API for writing third-party serverValidateHelper framework plugins (e.g. React Router)

[cr101]

Summary

v2's ServerValidateFrameworkPlugin interface is exported from @tanstack/form-core. But a plugin has nothing to call once it has decoded the request. The shipped Next.js plugin does its validation with validateServerValues from @tanstack/form-core/internals, which isn't in the main entry point. So any third-party plugin also has to import from /internals.

Could validateServerValues (or an equivalent) be exported from the main @tanstack/form-core entry and documented as stable for plugin authors?

Context

v2 removed @tanstack/react-form-remix. Its server plugins now cover only TanStack Start and Next.js, so React Router 7 users have no official way to do server validation. We don't think TanStack needs to own a React Router adapter. Making the plugin interface fully public would let the community write one, and the same goes for other frameworks.

There are already React Router questions with no supported answer:

• Tanstack Form + React Router 7? #1686 "Tanstack Form + React Router 7?"
• Can't use serverValidate with arrays [Zod, React Router 7] #1853 "Can't use serverValidate with arrays [Zod, React Router 7]"

What a React Router plugin looks like on 2.0.0-alpha.2

This is almost a copy of packages/react-form-nextjs/src/index.ts on alpha. The only problem is the import from /internals:

import { decode, type FormDataInfo } from 'decode-formdata'
import { validateServerValues } from '@tanstack/form-core/internals' // not public
import type {
  FormOptions,
  FormValidators,
  ServerValidateFrameworkPlugin,
  ServerValidateResult,
} from '@tanstack/form-core'

type ReactRouterCreateServerValidate = <
  TFormData,
  const TFormValidators extends FormValidators<TFormData>,
  TSubmitReturn,
>(
  options: FormOptions<TFormData, TFormValidators, TSubmitReturn, unknown>,
) => (request: Request) => Promise<ServerValidateResult<TFormData, TFormValidators>>

export function reactRouter(
  options: { info?: FormDataInfo } = {},
): ServerValidateFrameworkPlugin<ReactRouterCreateServerValidate> {
  return {
    id: 'react-form-react-router',
    createServerValidate: (formOptions) => async (request) => {
      const formData = await request.formData()
      const values = (options.info ? decode(formData, options.info) : decode(formData)) as never
      return validateServerValues(formOptions, values)
    },
  }
}

The route action would then be:

const { createServerValidate } = serverValidateHelper({ framework: reactRouter() })
const serverValidate = createServerValidate(formOpts)

export async function action({ request }: Route.ActionArgs) {
  const result = await serverValidate(request)
  if (!result.success) return data({ serverState: result.serverState }, { status: 400 })
  // ...persist result.values
}

Ask

1. Export validateServerValues (or a plugin-facing wrapper) from @tanstack/form-core and treat it as public API.
2. Optionally, add a short "Writing a server framework plugin" guide, so /internals isn't the documented path.

This fits the plugin-options rework in #2370, so it may be easiest to settle both together before v2 is stable.

[LeCarbonator]

It can't yet, because the SSR adapters are doing too much work right now. We need to change the architecture of the SSR process first so that the plugin only does the parts that it actually needs to do.

Until then, it will likely break. We are looking to make the final shape of it stable by v2 release, though.