perf(router-core): optimize buildLocation path resolution

[Sheraff]

Inspired by #8086

Summary

• return normalized absolute paths directly from resolvePath, avoiding the LRU, split, join, and final regex pass
• resolve relative buildLocation destinations in one pass instead of first resolving from against .
• normalize relative bases containing repeated slashes before parent traversal, preserving cases such as /a//b + ../../c -> /c
• reuse inherited params until an updater or route stringifier can mutate them, then clone lazily
• preserve repeated-slash and trailing-slash behavior and protect current params from mutating stringifiers

The production diff is ten net lines: path.ts adds 14 and router.ts removes 4. Benchmark source is intentionally not included in this PR.

Benchmark setup

The benchmark constructs a real RouterCore with a 1,200-route tree and executes 1,200 buildLocation() calls per sample. Production, browser-conditioned bundles run in Node with createMemoryHistory and RouterCore configured as server. Baseline (main) and the final candidate were bundled separately, loaded into the same process, and alternated for 1,500-2,000 samples. Each case was also rerun with candidate/baseline construction order reversed.

Times below are median milliseconds per 1,200 buildLocation() calls. Arrows are baseline -> candidate.

Important wins

repeated static absolute destinations
  baseline first:  0.858 -> 0.669 ms  (-22.0%)
  candidate first: 0.898 -> 0.722 ms  (-19.7%)

repeated relative destinations
  baseline first:  1.048 -> 0.897 ms  (-14.4%)
  candidate first: 1.058 -> 0.909 ms  (-14.0%)

1,200 unique relative destinations (sustained LRU misses)
  baseline first:  1.619 -> 1.542 ms  (-4.7%)
  candidate first: 1.619 -> 1.557 ms  (-3.8%)

1,200 mixed unique destinations
  baseline first:  1.972 -> 1.010 ms  (-48.8%)
  candidate first: 1.872 -> 1.009 ms  (-46.1%)

The mixed-unique case intentionally exceeds the 1,000-entry resolve-path LRU. The large win comes from one-off absolute destinations bypassing the LRU instead of evicting useful relative-path entries. It is a large-app/cache-pressure case, not the expected gain for every navigation.

The unique-relative case also exceeds the LRU and measures the final redundant cleanPath scan on every relative cache miss. Repeated relative paths that remain cached do not receive this additional 3.8-4.7% gain.

The repository Vitest benchmark, rerun in production mode in separate processes, also improved:

1,200 unique mixed destinations:   2.418 -> 1.507 ms  (37.7% faster)
1,200 repeated mixed destinations: 1.623 -> 1.459 ms  (10.1% faster)
1,200 double-slash destinations:   2.450 -> 1.568 ms  (36.0% faster)

Neutral case

repeated dynamic-param destinations
  baseline first:  2.133 -> 2.130 ms  (-0.1%)
  candidate first: 2.091 -> 2.083 ms  (-0.4%)

The sub-percent differences should be treated as no demonstrated change.

Bundle size

react-router.minimal compared with main:

gzip:   85,828 -> 85,844 bytes  (+16)
raw:   268,920 -> 269,051 bytes  (+131)
brotli: 74,750 -> 74,768 bytes  (+18)

Test plan

• pnpm nx run @tanstack/router-core:test:unit -- tests/path.test.ts tests/build-location.test.ts tests/optional-path-params.test.ts tests/optional-path-params-clean.test.ts
• pnpm nx run @tanstack/router-core:test:types
• pnpm nx run @tanstack/router-core:test:eslint
• react-router.minimal bundle-size comparison

Summary by CodeRabbit

• Bug Fixes

  • Improved URL path resolution by normalizing duplicate slashes.
  • Applied trailing-slash settings consistently to absolute paths.
  • Preserved route parameters when generating locations, preventing accidental mutation of current route state.
  • Ensured inherited parameters remain unchanged when building or updating locations.

• Tests

  • Added coverage for repeated slashes and trailing-slash modes.
  • Added regression coverage for parameter formatting without state mutation.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 4b877ce

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	11m 21s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	2m 2s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-19 00:41:27 UTC

[github-actions]

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

[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: d6b04845-ac67-41eb-a775-c0dde2600356

📥 Commits

Reviewing files that changed from the base of the PR and between 6bcaf84 and 4b877ce.

📒 Files selected for processing (2)

• packages/router-core/src/path.ts
• packages/router-core/tests/path.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Router-core now normalizes duplicate slashes during path resolution and applies trailing-slash settings directly. Location construction and parameter updates preserve shared route parameters during stringification and updates.

Changes

Router path and parameter handling

Layer / File(s)	Summary
Normalize destination paths packages/router-core/src/path.ts, packages/router-core/src/router.ts, packages/router-core/tests/path.test.ts, packages/router-core/tests/build-location.test.ts	resolvePath normalizes repeated slashes and handles absolute destinations according to trailingSlash. Router code passes destinations directly to the resolver. Tests cover traversal, base paths, and trailing-slash modes.
Preserve route parameters packages/router-core/src/router.ts, packages/router-core/tests/build-location.test.ts	Location construction and updater-based parameter changes avoid mutating shared parameter objects. Regression coverage verifies parameter immutability during stringification.

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

Merge Risk: ⚪ Minimal · up to 4b877

This PR optimizes router path resolution and parameter handling without introducing a known user-facing correctness or production risk; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• TanStack/router#7897: Both modify RouterCore.buildLocation and parameter handling.
• TanStack/router#8018: Both modify resolvePath behavior for path normalization.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: optimizing buildLocation path resolution.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/build-location-path-resolution

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 931e51a568

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Bundle Size Benchmarks

• Commit: a837a5f77928
• Measured at: 2026-08-19T00:31:21.976Z
• Baseline source: history:a78f2af5b49b
• Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	83.83 KiB	+16 B (+0.02%)	83.70 KiB	262.75 KiB	73.02 KiB	▃▃██▆▃▃▂▂▁▁▂
react-router.full	87.33 KiB	+20 B (+0.02%)	87.20 KiB	274.46 KiB	76.10 KiB	▄▅██▅▂▂▂▂▁▁▃
solid-router.minimal	33.19 KiB	+10 B (+0.03%)	33.06 KiB	96.61 KiB	30.01 KiB	████▅▁▁▁▁▇▇█
solid-router.full	38.04 KiB	+21 B (+0.05%)	37.91 KiB	111.25 KiB	34.26 KiB	▅▅▅▅▄▁▁▁▁▇▇█
vue-router.minimal	49.53 KiB	+28 B (+0.06%)	49.41 KiB	138.65 KiB	44.70 KiB	▇███▄▁▁▁▁▁▁▃
vue-router.full	55.14 KiB	+23 B (+0.04%)	55.01 KiB	156.85 KiB	49.60 KiB	████▄▁▁▁▁▁▁▃
react-start.minimal	96.73 KiB	+29 B (+0.03%)	96.59 KiB	305.00 KiB	83.72 KiB	▄▄▇▇▄▂▂▁▁▆▆█
react-start.deferred-hydration	97.45 KiB	+23 B (+0.02%)	96.61 KiB	306.36 KiB	84.40 KiB	▃▃██▅▃▃▁▁▆▆█
react-start.full	99.89 KiB	+24 B (+0.02%)	99.75 KiB	314.74 KiB	86.58 KiB	▄▄██▄▁▁▁▁▆▆▇
react-start.rsbuild.minimal	100.06 KiB	+47 B (+0.05%)	99.89 KiB	315.36 KiB	86.26 KiB	▁▁▆▆▅▂▂▁▁▅▅█
react-start.rsbuild.minimal-iife	100.47 KiB	+47 B (+0.05%)	100.30 KiB	316.30 KiB	86.70 KiB	▁▁▆▆▆▂▂▁▁▅▅█
react-start.rsbuild.full	103.38 KiB	+46 B (+0.04%)	103.21 KiB	325.45 KiB	89.02 KiB	▁▁▆▆▆▂▂▁▁▅▅█
solid-start.minimal	46.03 KiB	+15 B (+0.03%)	45.90 KiB	137.71 KiB	40.95 KiB	▅▅▅▅▃▁▁▁▁▇▇█
solid-start.deferred-hydration	49.11 KiB	+14 B (+0.03%)	45.97 KiB	145.17 KiB	43.74 KiB	▅▅▅▅▃▁▁▁▁▇▇█
solid-start.full	51.10 KiB	+10 B (+0.02%)	50.97 KiB	153.09 KiB	45.37 KiB	▅▅▅▅▃▁▁▁▁▇▇█
vue-start.minimal	65.67 KiB	+22 B (+0.03%)	65.55 KiB	189.49 KiB	58.47 KiB	▅▆▆▆▄▁▁▁▁▇▇█
vue-start.full	69.50 KiB	+26 B (+0.04%)	69.37 KiB	201.80 KiB	61.78 KiB	▅▅▅▅▃▁▁▁▁▇▇█

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsbuild
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@8108

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8108

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8108

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@8108

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@8108

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@8108

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@8108

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8108

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@8108

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@8108

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@8108

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@8108

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@8108

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@8108

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@8108

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@8108

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@8108

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@8108

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8108

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@8108

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8108

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@8108

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8108

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8108

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@8108

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@8108

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@8108

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@8108

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8108

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@8108

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@8108

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8108

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@8108

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@8108

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8108

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@8108

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8108

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8108

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@8108

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@8108

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@8108

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@8108

commit: 4b877ce

[codspeed-hq]

Merging this PR will regress 0 benchmarks

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 14 improved benchmarks
❌ 2 (👁 2) regressed benchmarks
✅ 164 untouched benchmarks

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Memory	mem server error-paths redirect (solid)	998.3 KB	382.2 KB	×2.6
⚡	Memory	mem client unique-location-churn (solid)	419.3 KB	266.2 KB	+57.5%
⚡	Memory	mem client interrupted-navigations (react)	294.5 KB	213.8 KB	+37.74%
⚡	Memory	mem client interrupted-navigations (solid)	288.4 KB	213.7 KB	+34.97%
⚡	Memory	mem client navigation-churn (solid)	819 KB	631.7 KB	+29.66%
⚡	Memory	mem client interrupted-navigations (vue)	455.1 KB	357.6 KB	+27.25%
⚡	Memory	mem server error-paths unmatched (react)	550.6 KB	433.2 KB	+27.09%
⚡	Memory	mem client unique-location-churn (vue)	559.5 KB	447.3 KB	+25.08%
⚡	Memory	mem server error-paths not-found (react)	481.8 KB	406.5 KB	+18.52%
⚡	Memory	mem server error-paths redirect (react)	318.7 KB	288.6 KB	+10.44%
⚡	Memory	mem server request-churn (vue)	868.6 KB	816.6 KB	+6.37%
⚡	Memory	mem server aborted-requests (vue)	1,069.1 KB	1,019.6 KB	+4.86%
⚡	Simulation	ssr dehydrate plain control (react)	354.2 ms	341.4 ms	+3.74%
⚡	Memory	mem client navigation-churn (vue)	1.5 MB	1.5 MB	+3.5%
👁	Memory	mem server error-paths redirect (vue)	401 KB	423.6 KB	-5.33%
👁	Memory	mem server serialization-payload (vue)	4.3 MB	4.5 MB	-5.44%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing perf/build-location-path-resolution (4b877ce) with main (a78f2af)}