feat(router-core): pass destination location to route lifecycle hooks #8774
main fromrefs/pull/8774/head·opened 🎯 Changes#
Closes #7778.
onEnter, onStay and onLeave only received the route match, so a consumer could not see the URL/search the navigation was resolving to. This adds a RouteLifecycleContext second argument carrying the destination ParsedLocation:
onEnter: (match, { location }) => { ... }
onStay: (match, { location }) => { ... }
onLeave: (match, { location }) => { ... }
location is the destination in all three phases: the newly matched branch for onEnter/onStay, the destination that replaces the leaving route for onLeave.
Implementation:
route.ts: exportedRouteLifecycleContext({ location: ParsedLocation }), updated the three hook signatures.router.ts:runRouteLifecycletakes the destination and passes{ location }to every hook.load-client.ts: dispatch withrouter.stores.location.get(), which holds the destination at commit time.load-server.ts: dispatch with the server-sidenextlocation.index.ts: export the type.- docs: documented the argument on all three hooks.
- changeset: minor bump for
@tanstack/router-core.
One-parameter hooks keep working; nothing else changes behaviour.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
- I fully understand the code in this pull request, including any code generated with AI assistance.
Local verification (not run in CI-equivalent full mode):
cd packages/router-core && npx vitest run
Test Files 139 passed (139)
Tests 3654 passed | 4 expected fail | 3 skipped
npx tsc -p tsconfig.json --noEmit # clean
pnpm --filter @tanstack/router-core build # clean
npx prettier --check <changed files> # clean
eslint on the touched files reports 41 pre-existing problems, identical before and after the change (git stash comparison). I did not run the React/Solid/Vue e2e suites here, so CI is the source of truth for those.
New tests: tests/lifecycle-dispatch.test.ts covers all three hooks receiving the destination; tests/callbacks.test.ts now asserts the destination href per hook (onLeave from /foo → /bar, onStay with a changed search). Existing stubs/benchmarks were updated for the new internal signature.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
AI assistance disclosure: implemented with an AI agent (Hermes) on my machine; I reviewed the diff, ran the tests above, and can maintain the change.
Summary by CodeRabbit#
New Features
- Route lifecycle callbacks now receive destination location context during navigation.
- Added the public
RouteLifecycleContexttype for accessing destination details. - Existing callbacks that use only the match argument remain compatible.
Documentation
- Updated lifecycle callback documentation to describe destination locations and active-branch requirements.
Tests
- Added coverage confirming destination URLs are available across client, server, query-string, and loading scenarios.
- 1
🦋 Changeset detected#
Latest commit: 6fa49a9303c58b4437514ca23a95123201657ac8
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 23 packages
Name Type @tanstack/router-core Minor @tanstack/react-router Patch @tanstack/react-start-client Patch @tanstack/react-start-rsc Patch @tanstack/react-start-server Patch @tanstack/router-generator Patch @tanstack/router-plugin Patch @tanstack/solid-router Patch @tanstack/solid-start-client Patch @tanstack/solid-start-server Patch @tanstack/start-client-core Patch @tanstack/start-plugin-core Patch @tanstack/start-server-core Patch @tanstack/start-storage-context Patch @tanstack/vue-router Patch @tanstack/vue-start-client Patch @tanstack/vue-start-server Patch @tanstack/react-start Patch @tanstack/router-cli Patch @tanstack/router-vite-plugin Patch @tanstack/solid-start Patch @tanstack/start-static-server-functions Patch @tanstack/vue-start Patch Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR
isihigameKoudai(GitHub profile, opens in a new tab) linked this to fix #7778
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
c8b60881-8974-4548-8c55-7d0da5e66ed2📥 Commits
Reviewing files that changed from the base of the PR and between 52da5039d358c3122c0491e0f274f25d5e736710 and 6fa49a9303c58b4437514ca23a95123201657ac8.
📒 Files selected for processing: 1
.changeset/lifecycle-destination-location.mdIncluded review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.
📝 Walkthrough
Route lifecycle callbacks now receive a
RouteLifecycleContextwith the destination location. Client and server dispatch pass that location to lifecycle execution, and tests verify the callback context.Changes: Route lifecycle destination context
packages/router-core/src/route.ts,packages/router-core/src/index.ts,docs/router/api/router/RouteOptionsType.mdRouteLifecycleContext, updates theonEnter,onStay, andonLeavesignatures, and documents the destination location.packages/router-core/src/load-client.ts,packages/router-core/src/load-server.ts,packages/router-core/src/router.ts,packages/router-core/tests/*,.changeset/lifecycle-destination-location.mdPriority: ⬇️ Low
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Feature
Sequence Diagram(s)#
Possibly related PRs
Merge Risk: ⚪ Minimal · up to
6fa49The lifecycle destination context is consistently delivered across the inspected client and server paths, with no merge-blocking risk identified.
Pre-merge checks:
4 · 
1
#7778requires the destination location inonEnter,onStay, andonLeave. The PR adds the exportedRouteLifecycleContext, updates all three callback signatures, passes the client and serv…#7778. Source changes implement the context and lifecycle dispatch. Exports, documentation, changeset, tests, and benchmark updates support the API change. No unrelated f…Full details: Description check
Explanation
The description is complete and follows the required template. It explains the change and motivation, records testing and known limitations, completes the checklist, documents release impact and the changeset, and discloses AI assistance.
Full details: Linked Issues check
Explanation
Issue
#7778requires the destination location inonEnter,onStay, andonLeave. The PR adds the exportedRouteLifecycleContext, updates all three callback signatures, passes the client and server destination locations, updates documentation, and adds runtime tests for all three hooks.Full details: Out of Scope Changes check
Explanation
The changes stay within issue
#7778. Source changes implement the context and lifecycle dispatch. Exports, documentation, changeset, tests, and benchmark updates support the API change. No unrelated functional change is shown.Full details: Docstring Coverage
Explanation
Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 11 files. (1 skipped: 1 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share