Skip to content
Source
Sign inSign up
TanStack/router

feat(router-core): pass destination location to route lifecycle hooks #8774

OpenisihigameKoudai(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/8774/headopened

🎯 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.
    1. Review in Change Stack →

      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 52da5039d358c3122c0491e0f274f25d5e736710 and 6fa49a9303c58b4437514ca23a95123201657ac8.

      📒 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

      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: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring 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 Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely describes the primary change: passing the destination location to route lifecycle hooks.
      Description checkPassedThe 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 checkPassedIssue #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 checkPassedThe 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
      Comment `@coderabbitai help` to get the list of available commands.
    2. 🦋 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
      NameType
      @tanstack/router-coreMinor
      @tanstack/react-routerPatch
      @tanstack/react-start-clientPatch
      @tanstack/react-start-rscPatch
      @tanstack/react-start-serverPatch
      @tanstack/router-generatorPatch
      @tanstack/router-pluginPatch
      @tanstack/solid-routerPatch
      @tanstack/solid-start-clientPatch
      @tanstack/solid-start-serverPatch
      @tanstack/start-client-corePatch
      @tanstack/start-plugin-corePatch
      @tanstack/start-server-corePatch
      @tanstack/start-storage-contextPatch
      @tanstack/vue-routerPatch
      @tanstack/vue-start-clientPatch
      @tanstack/vue-start-serverPatch
      @tanstack/react-startPatch
      @tanstack/router-cliPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/solid-startPatch
      @tanstack/start-static-server-functionsPatch
      @tanstack/vue-startPatch

      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

Sign in to join this conversation.