Proposal: Server Error Mapping & Success Flow Utilities (as an optional package)
Hi everyone đź‘‹
We often see questions about how to inject server-side validation errors into TanStack Form, and how to handle success flows (reset, flash messages, redirects, etc.) consistently. Right now it’s possible, but every team ends up writing their own boilerplate.
I’d like to explore creating a small optional package (e.g. @tanstack/form-server) that would provide simple utilities
- mapServerErrors(error, { pathMapper, fallbackFormMessage }) → normalize server responses into { fields, form }
- applyServerErrors(form, mapped) → inject those errors into the form state
- onServerSuccess(form, result, { resetStrategy, flash, after }) → handle resets / flash messages / post-submit callbacks
Why external package?
- Keeps the core headless and environment-agnostic
- Works with different server frameworks (Next.js, Remix, REST, GraphQL)
- Provides a standard DX for common “happy/unhappy path” scenarios
Questions for the community
- Would this solve a real pain point for you?
- Do you prefer it as a separate optional package, or should parts of it live in the core?
- Any must-have behaviors you’d expect (e.g. array path handling, global form error vs field errors)?
Thanks for your thoughts 🙏
4 Replies
afraid-scarlet•3w ago
I am 100% for having helpers to handle server-side validation and flows, and your suggested utilities seem reasonable for different use-cases.
Regarding your questions:
1. Of course. To me, a form is useless without custom server-side success & error flows that can be returned to the client, and I didn't find a way to do so with the current implementation (see https://discord.com/channels/719702312431386674/1100437019857014895/1399870454705160302).
2. Both work, but personally it would make more sense to have it built in the library as e.g.
@tanstack/form/server/next.
3. Global and per-field errors are a must. Returning custom data/objects would be great as well.ambitious-aquaOP•3w ago
Thanks for the feedback!
I've actually implemented exactly what you described and created a PR for it: https://github.com/TanStack/form/pull/1730
The @tanstack/form-server package includes:
- Global and per-field error handling
- Custom server-side success & error flows
- Support for custom data/objects
- Works with Zod, Rails, NestJS, and custom error formats
- Comprehensive React integration guide
Would love to get your thoughts on the implementation!
GitHub
Add @tanstack/form-server Package by jiji-hoon96 · Pull Request #1...
This PR introduces a new @tanstack/form-server package that provides utilities for handling server errors and success responses in TanStack Form applications.
Key Features
Error Normalization: map...
afraid-scarlet•3w ago
Great outline! I've only read the documentation and it's a good start, though I do have some questions/concerns.
1. I see different validation library/types of error objects supported. Just confirming that Standard Schema v1 is supported?
2.
@tanstack/form already has a createServerValidate function which can automatically return the validated form data by a schema resolver. Would be wonderful to see this used in the examples for @tanstack/form-server. This would remove redundant code such as here.
3. Small nitpick, but isn't it better to map the server errors in the server function so we don't need to do so client-side?
4. How would the client-side react if server-side functions such as Next.js' redirect are called? Is returning a response object still necessary then?
5. I don't see an example where global/root errors are shown? Only field errors.ambitious-aquaOP•3w ago
Thank you for the detailed feedback! I've implemented all the requested changes.
I added Standard Schema v1 support with highest priority processing, ensuring it's handled before other validation formats. The new createServerErrorResponse and createServerSuccessResponse functions allow server-side error mapping, reducing client-side processing as you suggested.
For server redirects, I added an onRedirect callback option to handle Next.js redirect() calls and similar scenarios. I also added helper functions like getFormError, hasFieldErrors, and getAllErrorMessages to properly display global/root errors in the UI.
All changes maintain backward compatibility and include comprehensive test coverage (94.2% coverage, 61 tests passing). The package now provides better integration with createServerValidate and follows a server-first approach for error handling.
Let me know if you'd like any adjustments to these implementations.