npm / @tanstack/react-router
@tanstack/react-router
What changed in @tanstack/react-router 1, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.
40 breaking2 security1 deprecations1 new APIs and options14 performance2 behavior and defaults1 tooling39 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@tanstack/react-router 1100 changes
Breaking changes 40
Router requests whose Accept header allows neither text/html nor */* now receive 406 Not Acceptable instead of 500.
Active and inactive Link props override base element props, including refs and event handlers, while router-controlled href, disabled, and target values retain precedence.
The internal helper is no longer exported.
The internal helper is no longer exported.
React and Vue boundary error components and onCatch callbacks now type boundary errors as unknown; narrow errors before accessing message or stack.
Structural descendants below error and not-found boundaries are excluded from lifecycle callbacks, while lifecycle membership is preserved through invalidation, hydration, background reloads, and superseded navigation publication.
Removes the undocumented data-transitioning attribute from Link.
Removes the undocumented Link isTransitioning state.
The method now returns a tuple of matched routes, raw params, and the found route; preserving raw path params gives structured params stable match IDs and prevents stale loader data reuse.
RouteMatch.fetchCount has been removed with no replacement; it was purely informational.
The standalone @tanstack/router-core export has been removed; use the router.getMatchedRoutes() instance method instead.
The exported type has been removed along with the method it typed.
Exported React, Solid, and Vue Match components now accept routeId instead of matchId.
Removed from MatchRoutesOpts.
Removed from MatchRoutesOpts.
The former globalNotFound field is renamed and privatized; use match.status === 'notFound' instead.
Removed; it was internal redirect bookkeeping.
The status union no longer includes 'redirected'; redirected matches are dropped from the match list instead of being rendered.
Removed with no replacement.
Removed, with no replacement for cancelling an individual in-flight match from outside the router.
Removed, with no replacement for cancelling in-flight matches from outside the router.
Removed; expired cache entries are now reconciled automatically as part of match commit.
Replaced by the internal _commitPromise field.
Removed; read matches from router.state.matches instead.
Removed with no replacement.
Removed; check router.state.matches for a match whose status is 'notFound'.
Removed with no replacement.
Removed with no replacement.
Removed with no replacement.
The optional second argument no longer accepts an array of component types; it now accepts 'errorComponent', 'notFoundComponent', or false for internal boundary loading. One-argument usage is unchanged.
Removed; use routesById.
Replaced by the internal _pendingLocation field.
Removed, with no replacement for mutating an individual in-flight match from outside the router.
Removed with no replacement.
RouterState no longer exposes loadedAt, isTransitioning, statusCode, or redirect; use match.updatedAt and router.state.status / router.state.isLoading where indicated, while server response status and redirect handling are internal.
The adapter contract now uses ids, byRoute, and getMatchStore() instead of matchesId, matchStores, and getRouteMatchStore(); separate loading/status/cache stores and their setters are removed, and application-facing state should be read from router.state.
The signature is now (fn, expected) => Promise<boolean> instead of (fn) => void; custom framework adapters implementing startTransition are affected.
StoreConfig.init has been removed.
The exported type has been removed along with the method it typed.
The script callback context now exposes only kind: 'script' and url; script format handling remains internal to manifest rendering.
Security 2
Destinations are validated, ambiguous relative URLs stay on the current origin, and configured origins must already be normalized.
Prerender requests and output paths are constrained.
Deprecations 1
Warns when an Outlet is rendered inside a pending, error, or not-found component.
New APIs and options 1
Configure allowed path parameter characters when creating the router; changing them requires a new router instance.
Performance 14
Pending link preload timers are canceled when navigation starts to avoid redundant preloading while the destination is loading.
Link href classification and active/inactive results are reused across location updates while live history href formatting is preserved.
Skips unused Link preload cleanup when preloading is disabled.
Links reuse built locations when destinations do not depend on the current location; params, search, and activeOptions are compared by value, so unchanged inline objects reuse the location.
Shared Link pathname interpolation reduces bundle cost while preserving rendering performance.
Link SSR rendering is 20–40% faster in benchmarks, and the React Start SSR request loop is about 7% faster.
Links without user-supplied event handlers avoid allocating event-handler arrays and wrapper functions.
React Links reduce bundle size and avoid temporary class-name arrays and unnecessary style copies.
Cancels pending preloads when links leave the viewport.
Link now bails out of re-renders when the resolved href and active state are unchanged.
Sharing structuralSharing selector logic reduces bundle size.
Navigations trigger fewer Match rerenders.
useMatch and derived hooks perform better when navigating away from the previous match.
During SSR, useMatches can skip useRef for structural sharing.
Behavior and default changes 2
CatchBoundary is directly exported as a class component, removing the function wrapper.
Client entry scripts and preloads are now represented as root route manifest assets.
Tooling 1
Adds support for module output by default and IIFE output for classic script environments.
Fixes and other changes 39
Builds mask and routeMasks locations from the same _fromLocation as the destination.
Links for routes left by a pending navigation skip deriving the destination location, and clicks and preloads follow the href the Link displays.
Fixed Link destinations resolving to a route mask are reused across navigations; mounted Links follow changes to href and reloadDocument props.
Only enabled route boundaries are composed, rather than rendering inactive wrapper components.
Ignores queued viewport notifications after their effect has been cleaned up.
Links that do not compare URL hashes no longer trigger hydration rerenders, while hash-sensitive active state and ClientOnly behavior are preserved.
Large deferred SSR hydration payloads stream through a backpressure-aware router transport; cancelled or expired transforms close safely.
Element props pass through as given for external links, including falsy values; useLinkProps also returns children for router-controlled links.
Blocked-link inactive props remain consistent during React hydration.
Native form HTTP redirects, route error handling, and masks are preserved for document redirects.
Explicit redirect Location headers are honored before route options are checked.
Redirect headers no longer appear in serialized server function response bodies.
Shared loader redirects retain per-navigation destinations.
React and Vue error boundaries preserve falsy thrown values; SSR wraps non-Error loader errors and retains the original value in cause.
React no longer repeats innerHTML writes for unchanged styles and data scripts during re-renders, avoiding unnecessary CSS parsing and Trusted Types errors during client navigation.
Successful not-found matches remain terminal shared boundaries during client navigation, preserving route context while the destination loads.
The route-scoped API now forwards shouldThrow and preserves optional return types when shouldThrow is false.
The route-scoped API now forwards shouldThrow and preserves optional return types when shouldThrow is false.
The route-scoped API now forwards shouldThrow and preserves optional return types when shouldThrow is false.
Context is preserved during reloads.
Pending UI is preserved across retained routes.
Resolved lazy route components are reused when revisiting code-split routes, preventing unnecessary pending UI.
Root components that may render the HTML document are no longer wrapped in a Suspense boundary during SSR and hydration.
Updated useMatchRoute for use with React Compiler.
Applies preloadDelay to viewport link preloading.
Mounted UI is retained during revalidation.
A component-scoped React transition for match publication prevents a blank frame before zero-delay initial pending UI.
Intersection observer options in the link component are cleaned up.
The documented default is now 5 minutes (300_000), matching the existing runtime default.
Route headers() now runs only on the server and is no longer invoked during client-side asset projection.
Invalidation now retires matching active preloads so older speculative loader results cannot become fresh cache data afterward.
Match loading now tracks navigations, preloads, and background reloads as ordered work, preventing state leakage between overlapping navigations, restoring correct SSR response statuses, and avoiding rerunning server-completed work during hydration.
The documented default is now 5 minutes (300_000), matching the existing runtime default.
AbortError is silenced during renderRouterToStream because it is normal operation.
Search middleware composition no longer restores search params that a downstream stripSearchParams removed.
Preserves primitive values thrown from beforeLoad error handling.
Fixes streaming.
Script asset cross-origin configuration now uses the script key.
Fixes hash navigation being overridden by stale scroll restoration entries.