| published | 2026-03-24 | |
|---|---|---|
| authors |
|
|
| title | TanStack Router's New Reactive Core: A Signal Graph | |
| excerpt | TanStack Router now uses a granular signal graph as its reactive core. State is derived from that graph, which narrows change propagation and makes client-side navigation faster in our benchmarks. |
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:
- more targeted updates,
- fewer store updates during navigation,
- faster client-side navigation in our benchmarks,
- the Solid adapter now uses native Solid signals internally.
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:
A video showing that on every stateful event in the core of the router, changes are propagated to every subscription across the entire application.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.
- top-level stores for location, status, loading, transitions, redirects, and similar scalar state
- per-match stores grouped into pools of active matches, pending matches, and cached matches.
- derived stores for specific purposes like "is any match pending"
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:
A video showing that on each stateful event in the core of the router, only a specific subset of subscribers are updated in the application.Note
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.
// Before
useRouterState({
select: (state) => {
const match = state.matches.find((m) => m.routeId === routeId)
return /* select from one match */
}
})
// After
const matchStore = router.stores.getMatchStoreByRouteId(routeId)
useStore(matchStore, (match) => /* select from one match */)This is an internal implementation detail, not a new public API surface for application code.
Note
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.
The refactor also moves the store implementation behind a shared contract.
The router core defines the interface. Each adapter provides the implementation.
export interface RouterReadableStore<TValue> {
readonly state: TValue
}
export interface RouterWritableStore<TValue> {
readonly state: TValue
setState: (updater: (prev: TValue) => TValue) => void
}
export type StoreConfig = {
createMutableStore: MutableStoreFactory
createReadonlyStore: ReadonlyStoreFactory
batch: RouterBatchFn
init?: (stores: RouterStores<AnyRoute>) => void
}| 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.
Note
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
- React:
7ms -> 4.5ms - Solid:
12ms -> 8ms - Vue:
7.5ms -> 6ms
main (grey) and on refactor-signals (blue).
main (grey) and on refactor-signals (blue).
main (grey) and on refactor-signals (blue).
There is also a bundle-size tradeoff. In our synthetic bundle-size benchmarks, measuring gzipped sizes:7
- ↗ React increased by
~1KiB - ↗ Vue increased by
~1KiB - ↘ Solid decreased by
~1KiB
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.
Footnotes
-
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. ↩