fix(router-core): stringify parent params for missing route templates

[xianjianlf2]

Fixes #7877.

When Start prunes a server-only leaf route from the client route tree, a client-side buildLocation() call for that route template cannot find an exact routesByPath entry. The current fallback leaves destRoutes empty for route templates, so parent params.stringify hooks are skipped and the generated href can differ from SSR.

This keeps exact route-template matches unchanged, but when a template is missing it falls back to the longest known parent route branch. That gives parent routes a chance to canonicalize path params while still leaving the server-only leaf absent from the client route tree.

The regression test models the client route tree after a server-only child was pruned: only /$postType exists locally, while a link is built for /$postType/$postId/download. The parent stringify maps article back to the canonical articles segment.

Tests run:

• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/history build
• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/router-core test:unit --run tests/build-location.test.ts -t "matched parent of a missing route template"
• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/router-core test:unit --run tests/build-location.test.ts
• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/router-core test:unit
• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/router-core test:types:ts70
• PATH=/opt/homebrew/bin:$PATH pnpm --dir packages/router-core test:eslint
• PATH=/opt/homebrew/bin:$PATH pnpm exec prettier --check packages/router-core/src/router.ts packages/router-core/tests/build-location.test.ts

Note: test:eslint exits 0 with existing warnings in unrelated router-core files.

Summary by CodeRabbit

• Bug Fixes
  • Improved navigation to template-based destinations when a deeply nested route is not available in the client route tree.
  • Preserved parameter formatting and canonical URL generation using the nearest known parent route.
  • Ensured nested paths resolve correctly, including transformed URLs such as /articles/1/download.
  • Prevented incomplete route chains and incorrect destination URLs during navigation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 10d651b0-cd61-4d3c-81eb-6045d1b10881

📥 Commits

Reviewing files that changed from the base of the PR and between 783f883 and 8a73edd.

📒 Files selected for processing (2)

• packages/router-core/src/router.ts
• packages/router-core/tests/build-location.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/router-core/src/router.ts

---

📝 Walkthrough

Walkthrough

RouterCore.buildLocation now uses the nearest known parent route branch when a typed destination’s leaf template is missing. This preserves parent parameter stringification. A regression test verifies canonical URL generation for a server-only child route.

Changes

Router parent canonicalization

Layer / File(s)	Summary
Parent branch fallback and regression coverage packages/router-core/src/router.ts, packages/router-core/tests/build-location.test.ts	buildLocation finds the nearest known parent route branch for template-based destinations without a client leaf route. The test confirms that the parent params.stringify transformation produces /articles/1/download.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• TanStack/router#7966: Both changes update route parameter handling in router.ts, but they address different issues.

Suggested labels: package: router-core

Suggested reviewers: schiller-manuel

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the router-core fix for applying parent parameter stringification when the destination route template is missing.
Linked Issues check	✅ Passed	The fallback parent route branch and regression test address #7877 by preserving parent params.stringify for server-only destination routes.
Out of Scope Changes check	✅ Passed	The implementation and test are limited to the missing-route-template fallback and parent parameter stringification described in #7877.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[xianjianlf2]

Merged latest origin/main into fix/server-route-link-stringify-7877 and resolved the router-core conflict against the current tuple-based matching code. The parent-route fallback for missing server-only leaf templates is preserved so params.stringify still canonicalizes links.

Validation:

• pnpm install --frozen-lockfile
• pnpm exec prettier --check packages/router-core/src/router.ts packages/router-core/tests/build-location.test.ts
• pnpm --dir packages/history run build
• pnpm --dir packages/router-core exec vitest run tests/build-location.test.ts (73 passed, no type errors)

Current head: 8a73eddc2e54d879403637b8b6c96234ac0b54d3