[next.js] `initialFormState` and no fields rendered may cause `state.values` undefined

[MartinCura]

Describe the bug

Hi! Great library you have here. I've been using it for while now and first time i've come across this.

In the Next.js App Router guide (https://tanstack.com/form/latest/docs/framework/react/guides/ssr#app-router-integration) it recommends to set the initial server state with

import { initialFormState } from '@tanstack/react-form-nextjs'

// inside component:
  const [formState, action] = useActionState(someAction, initialFormState)
  // ...
  const form = useForm({
    transform: useTransform((baseForm) => mergeForm(baseForm, formState ?? {}), [formState]),
    // ...

but initialFormState as defined has values: undefined (see: https://github.com/TanStack/form/blob/6a5e1c1a4f0f0519705cc5fd15cbe8afb878a42d/packages/react-form-nextjs/src/createServerValidate.ts#L133)

This means that trying to access state.values.<field> will break as values is now undefined. In my case this cropped up trying to use <form.Subscribe>

Your minimal, reproducible example

None, sorry

Steps to reproduce

1. Clone https://github.com/MartinCura/tanstack-form-1923
2. pnpm i && pnpm run dev
3. Go to http://localhost:3000, reload page

Expected behavior

I expect values to always be defined, as should all of the fields in my schema.

The bug is in application code! ...but following the docs' recommendations 🤔, and using initialFormState which introduces the issue.

How often does this bug happen?

Often

Screenshots or Videos

No response

Platform

• Fedora
• Firefox / Zen

TanStack Form adapter

None

TanStack Form version

v1.27.1

TypeScript version

v5.9.3

Additional context

I'm not sure if this is a docs issue instead of any type of bug, i'll leave it up to you!

I'd say the bottom line is not sure why the values should be allowed to be undefined, and thus if either initialFormState should be something that adapts to the form schema, or outright don't recommend it and make the user write it manually, maybe copying the default values (which is more or less the fix i implemented).

[MartinCura]

Wait i've done a minimal repro and i can't reproduce 🤔 investigating...

[MartinCura]

Is the recommendation now to use the specific package @tanstack/react-form-nextjs for everything? I see it re-exports everything from @tanstack/react-form

[MartinCura]

Ok i think i'm pinning it down:

If there's a <form.Field> for a field, any field of the form, then it somehow ammends the values (even if it doesn't render anything itself).

In my case i have an <Activity mode={isSubmitSuccessful ? "visible" : "hidden"> wrapping the only field, which means no fields are being rendered on the first pass. If i either add another <form.AppField> that always renders or if i hide the field with CSS instead, then no error is thrown.

I'll upload a repro, clearly it was the correct path.

[MartinCura]

https://github.com/MartinCura/tanstack-form-1923

just look at the client-component.tsx

the first commit is a copy of the base example, except for package upgrades that leaked in there

[MartinCura]

So leaving that investigation here, hope it's useful, luckily it's clear that i can workaround this issue by always having some field rendered since the first pass.

[crutchcorn]

I suspect this work on my end may fix issues here:

https://github.com/TanStack/form/pull/1890

But I could be wrong. Will validate later

[MartinCura]

I suspect this work on my end may fix issues here:

#1890

But I could be wrong. Will validate later

Interesting, thank you for the quick answer!

It may be of interest that console.log'ing i see

• server-side: values defined
• client-side: values first defined then undefined

No hurry here, and do tell me if i can give a hand in debugging.