by Florian Pellet on Mar 31, 2026.
TanStack Router used to keep all of its reactive state in one large object: router.state. This refactor replaces that with a graph of smaller stores for the pieces of state that change independently. router.state still exists, but it is now derived from those stores instead of serving as the internal source of truth.
This builds on TanStack Store's migration1 to alien-signals, implemented by @DavidKPiano. In external benchmarks2, alien-signals performed very well. The faster primitive helps, but the bigger change is that this allows the router to track state in smaller pieces instead of routing everything through one broad store.
Concretely, this means:
The old model had one main reactive surface: router.state.
That was useful. It made it possible to prototype features quickly and ship a broad API surface without first designing a perfect internal reactive topology. But it also meant many different concerns shared the same reactive entry point.
| Concern | Stored under router.state | Typical consumer |
|---|---|---|
| Location | location, resolvedLocation | useLocation, Link |
| Match lifecycle | matches, pendingMatches, cachedMatches | useMatch, Matches, Outlet |
| Navigation status | status, isLoading, isTransitioning | pending UI, transitions |
| Side effects | redirect, statusCode | navigation and response handling |
This did not mean every update rerendered everything. Options like select and structuralSharing could prevent propagation. But many consumers still subscribed to more router state than they actually needed.
Routing state does not change as one unit. During a navigation, one match stays active, another becomes pending, one link changes state, and some cached matches do not change at all.
The old model captured those pieces of state, but all subscriptions still started from the same top-level state object. That mismatch shows up here:
In practice, many consumers subscribed to more router state than they actually needed.
The main change is that the smaller stores are now the source of truth, and router.state is rebuilt from them.
Instead of one broad state object, the router keeps separate stores with narrower responsibilities.
router.state still exists for public APIs, but it is now rebuilt from the store graph instead of serving as the internal source of truth.
The new picture looks like this:
Active, pending, and cached matches are now modeled separately because they have different lifecycles. This cuts down updates even further.
Before, the smaller pieces of state were derived from router.state. Now, router.state is derived from the smaller stores. That is the core of this refactor.
With the smaller stores as the source of truth, router internals can subscribe to the exact store they need instead of selecting from one large snapshot. The clearest example is useMatch.
Before this refactor, useMatch subscribed through the big router store and then searched state.matches for the match it cared about. Now it resolves the relevant store first and subscribes directly to it.
This is an internal implementation detail, not a new public API surface for application code.
getMatchStoreByRouteId creates the derived signal on demand and stores it in a Least-Recently-Used cache3 so other subscribers can reuse it without leaking memory.
The store-update-count graphs below show how many times subscriptions are invoked during various routing scenarios. The last point is this refactor.4
These graphs show that fewer subscribers are triggered during navigation.
Vue Router is mentioned throughout this article as a useful reference. However it is still a work in progress. Vue Vapor (3.6) is on the doorstep (beta.9 at the time of writing), so the plan is to do the Vapor refactor and then support that refreshed version.
The refactor also moves the store implementation behind a shared contract.
The router core defines the interface. Each adapter provides the implementation.
| Adapter | Store implementation |
|---|---|
| React | TanStack Store |
| Vue | TanStack Store |
| Solid | Solid signals |
This keeps one router core while letting each adapter plug in the store model it wants.
Solid's derived stores are backed by native memos, and the adapter uses a FinalizationRegistry5 to dispose detached roots when those stores are garbage-collected.
No new public API is required here. useMatch, useLocation, and <Link> keep the same surface. The difference is that navigation and preload flows now trigger fewer subscriptions.
Our benchmarks isolate client-side navigation cost on a synthetic rerender-heavy page.6
There is also a bundle-size tradeoff. In our synthetic bundle-size benchmarks, measuring gzipped sizes:7
React and Vue increased in size because representing the router as several stores takes more code than representing it as one state object. Solid decreased in size because it no longer depends on tanstack/store.
This refactor changes how reactivity is structured inside the router.
Before, router.state was the broad reactive surface and smaller pieces of state were derived from it. Now the smaller stores are primary, and router.state is a derived snapshot kept for the existing public API.
In practice, that means route changes update more locally and trigger less work during navigation.
js-reactivity-benchmark last updated January 2025 ↩
For a great JavaScript-oriented explanation of how LRU caches work, see Implementing an efficient LRU cache in JavaScript. ↩
Methodology and exact scenario assertions live in the adapter test files for React, Solid, and Vue. ↩
A FinalizationRegistry allows us to hook into the Garbage Collector to execute arbitrary cleanup functions when an object gets collected. ↩
These numbers come from the deterministic fixtures in benchmarks/bundle-size, measured from the initial-load JS graph and tracked primarily as gzip deltas. See the README. ↩
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。