[TRACKING] Breaking Changes Made During the RC Phase

[crutchcorn]

Well y'all, I hate to say it, but we'll have a few breaking changes during our RC "stable" phase.

We just released our first two breaking changes in 0.38.0:

• Dropped support for TypeScript 4.9 and 5.0
• Dropped support for Angular 17.3 and 18.x

And, unfortunately, it's not the only two breaking changes we'll be making. In addition, we need to introduce two breaking changes to our React adapters:

• Remove form.useField API, as it does not follow the rules of React Hooks
• Remove form.useStore API, as it does not follow the rules of React Hooks

Which will be merged here shortly as part of 0.39.0: #1035

While these breaking changes are unfortunate, there were a few factors at play:

1. I assumed dynamic hooks followed the rules of React Hooks, which turned out to be false, only discovered once the Compiler was more generally available
2. I didn't think we could integrate TanStack Store's fresh Derived API would be fast enough to validate in TanStack Form for some time. I was wrong.
   2b) Once I realized we could use TanStack Store, working on it made it clear that there were bugs in the Angular adapter and TypeScript types that we needed to ship downstream

I wish I could have foreseen these issues ahead of time, but alas I am only human. Needless to say, once we hit v1, we'll be much more careful to introduce these breaking changes in chunks (ala major versions) and with migration guides to avoid problems.

Moreover, to help make this second batch of React breaking changes a little easier, we'll help write migration guides for form.useField and form.useStore in our changelog for everyone impacted.

Again, immense apologies on my end. I was the one who made the call to introduce these breaking changes prior to v1. We'll work hard on avoiding doing so again in the immediate future.

[crutchcorn]

I was recently asked on our Discord:

What's the current state of Tanstack Form? I see that it's been in an RC phase for a few months, and there's a roadmap discussion tracking page.

Is it just the final issues listed in the road to 1.x discussion, or are there other changes/features planned before 1.x can be released?

Would love to use it in a production application at some point in the near future, but would like to know more about stability and if there are any holes in terms of common functionality moving over from something like react-hook-form.

I thought this was a great question and wanted to answer it in a more public-facing way as well.

Transparently, I'm trying to get as many potentially breaking changes (even tiny ones) out the door as quickly as I can while retaining the quality of our software. Here's one such (big) example:

#1104

Once this PR is merged (this/next week), we really only have two things to do:

• Shared component logic documentation and utility fns
• TanStack Start adapter fixes

Then we're v1.

In regards to stability, our announcement to the RC phase was a commitment to as much stability as we could forsee. We had two breaking changes per:

#1044

And #1104 might require some minimal refactor to fix some typing issues, but no runtime behavior will break (backed by our extensive test suite). I think the risk of using TanStack Form in production today is minimal and I'm already aware of some moderately high-profile usage of our product in prod today.

That said, here's my thoughts on where we stand today compared to RHF. Even today, prior to v1 we're:

• Much more compatible with React Compiler (confirmed support + tests)
• Much more compatible with Next.js/RSCs (confirmed support + tests)
• Field + form validation (only form validation for RHF)
• Substancially more type-safe (never typo a name)
• One API to learn, not many (Controller + {...props} + others)
• Standard schema support
• Framework agnostic (useful in large corpos)
• Handling async validation for you (debounce + AbortSignal support)

I think this puts us well above RHF in pragmatic terms today.