[isihigameKoudai]

🎯 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: exported RouteLifecycleContext ({ location: ParsedLocation }), updated the three hook signatures.
• router.ts: runRouteLifecycle takes the destination and passes { location } to every hook.
• load-client.ts: dispatch with router.stores.location.get(), which holds the destination at commit time.
• load-server.ts: dispatch with the server-side next location.
• 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 RouteLifecycleContext type 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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: TanStack/router/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: c8b60881-8974-4548-8c55-7d0da5e66ed2

📥 Commits

Reviewing files that changed from the base of the PR and between 52da503 and 6fa49a9.

📒 Files selected for processing: 1

• .changeset/lifecycle-destination-location.md

Included 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 RouteLifecycleContext with the destination location. Client and server dispatch pass that location to lifecycle execution, and tests verify the callback context.

Changes: Route lifecycle destination context

Layer / File(s)	Summary
Public context and callback signatures packages/router-core/src/route.ts, packages/router-core/src/index.ts, docs/router/api/router/RouteOptionsType.md	Adds and exports RouteLifecycleContext, updates the onEnter, onStay, and onLeave signatures, and documents the destination location.
Lifecycle dispatch and validation 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.md	Client and server dispatch pass the destination location to lifecycle execution. Callbacks receive it as their second argument. Tests, the benchmark, and the changeset cover the updated contract.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ClientRouter
  participant ServerRouter
  participant runRouteLifecycle
  participant LifecycleCallback
  ClientRouter->>runRouteLifecycle: pass current stored location
  ServerRouter->>runRouteLifecycle: pass destination location
  runRouteLifecycle->>LifecycleCallback: pass match and location context

Loading

Possibly related PRs

• TanStack/router#7817: Adds the same destination-location context to lifecycle callback types, dispatch, documentation, and tests.

Merge Risk: ⚪ Minimal · up to 6fa49

The lifecycle destination context is consistently delivered across the inspected client and server paths, with no merge-blocking risk identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		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: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: passing the destination location to route lifecycle hooks.
Description check		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 c…
Linked Issues check		Issue #7778 requires the destination location in onEnter, onStay, and onLeave. The PR adds the exported RouteLifecycleContext, updates all three callback signatures, passes the client and serv…
Out of Scope Changes check		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 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 #7778 requires the destination location in onEnter, onStay, and onLeave. The PR adds the exported RouteLifecycleContext, 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.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 6fa49a9

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