Proposal: useHistoryState hook for type-safe state management — feedback welcome (PR #3967)

[naoya7076]

Summary

This post is about Pull Request #3967, which proposes adding a new useHistoryState hook to TanStack Router to support typed state on a per-route basis. The goal is to enable type-safe handling of history.state passed during navigation without relying on global declarations.

Motivation

Currently, TanStack Router requires global HistoryState declarations to manage history.state in a type-safe way. This can lead to:

• Type pollution, where unrelated state types leak into unrelated contexts
• Interface bloat, as the global state interface grows unnecessarily large

This proposal addresses these issues by introducing a hook-based API that allows each route to define and access its own typed navigation state, eliminating the need for global state declarations.

What this PR adds

• A new useHistoryState hook for reading history.state in a type-safe manner
• Support for route-level state validation using validateState
• Enhancements to FileRoute to enable typed state usage
• A working example under examples/react/basic-history-state

Request for Feedback

The PR is ready for review, and I’d appreciate any feedback on the design, naming, API surface, or edge cases. I'm happy to iterate on the implementation to align with community expectations.
Thanks for your time and insights!

References

• Discussion #284 – How to replace location.state?
• Discussion #975 – Type-safe search params and related ideas