perf(router-core): cache lightweight route matches

[Sheraff]

Summary

• cache lightweight buildLocation route matching by ParsedLocation and last active match id
• reuse cached fullPath/search/params results for repeated lightweight matches

Testing

• git diff --check -- packages/router-core/src/router.ts

Summary by CodeRabbit

• Performance
  • Router performance has been improved through intelligent caching of route matching validation results, eliminating redundant processing and enabling faster navigation between routes. Application responsiveness has been significantly enhanced, particularly noticeable during route transitions and when handling complex dynamic navigation scenarios with parameter and search validation operations.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a WeakMap-based result cache to matchRoutesLightweight in RouterCore. It caches expensive route-match results keyed by ParsedLocation, validating cache hits by comparing stored and current match-state identifiers, and caches newly computed results before returning them.

Changes

Lightweight Route Matching Cache

Layer / File(s)	Summary
Cache type definitions and storage packages/router-core/src/router.ts	Type aliases for LightweightRouteMatchResult and LightweightRouteMatchCacheEntry structure the cached data shape; a private lightweightCache WeakMap is added to RouterCore to store cached match results keyed by ParsedLocation.
Cache lookup and hit detection packages/router-core/src/router.ts	matchRoutesLightweight checks the cache for an entry and compares its lastMatchId against stores.matchesId to return cached results when the match state has not changed.
Cache miss handling and result storage packages/router-core/src/router.ts	Old local lastStateMatchId initialization is removed; the method now builds the result object from matched routes, paths, and params, stores it in the cache with the current match state id, and returns the result.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A cache springs to life with parsed locations as keys,
Route matches now whisper "remember these, please!"
No wasteful revalidation when matches don't shift—
Just fetch from the WeakMap, a temporal gift.
Fast hops through the routes, no redundant expense! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a cache for lightweight route matches in router-core to improve performance.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/router-core-lightweight-cache

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 91b3196

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

---

☁️ Nx Cloud last updated this comment at 2026-06-13 16:42:24 UTC

[github-actions]

🚀 Changeset Version Preview

3 package(s) bumped directly, 10 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.15 → 1.170.16	Changeset
@tanstack/solid-router	1.170.15 → 1.170.16	Changeset
@tanstack/start-server-core	1.169.14 → 1.169.15	Changeset
@tanstack/react-start	1.168.25 → 1.168.26	Dependent
@tanstack/react-start-client	1.168.13 → 1.168.14	Dependent
@tanstack/react-start-rsc	0.1.24 → 0.1.25	Dependent
@tanstack/react-start-server	1.167.19 → 1.167.20	Dependent
@tanstack/solid-start	1.168.25 → 1.168.26	Dependent
@tanstack/solid-start-client	1.168.13 → 1.168.14	Dependent
@tanstack/solid-start-server	1.167.19 → 1.167.20	Dependent
@tanstack/start-plugin-core	1.171.17 → 1.171.18	Dependent
@tanstack/vue-start	1.168.24 → 1.168.25	Dependent
@tanstack/vue-start-server	1.167.19 → 1.167.20	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 2ff388e81de0
• Measured at: 2026-06-13T16:39:55.715Z
• Baseline source: history:36ed57409a98
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.33 KiB	+39 B (+0.04%)	87.19 KiB	273.80 KiB	76.00 KiB	▁▁▁▁▁▂▅▅▅▅▅█
react-router.full	91.06 KiB	+44 B (+0.05%)	90.92 KiB	285.70 KiB	79.10 KiB	██▁▁▁▁▄▄▄▄▄▇
solid-router.minimal	35.53 KiB	+47 B (+0.13%)	35.40 KiB	106.00 KiB	31.98 KiB	▂▂▂▃▁▁▁▁▁▁▁█
solid-router.full	40.58 KiB	+54 B (+0.13%)	40.46 KiB	121.22 KiB	36.50 KiB	▂▂▂▂▁▁▁▁▁▁▁█
vue-router.minimal	53.01 KiB	+40 B (+0.07%)	52.88 KiB	150.04 KiB	47.68 KiB	▁▁▁▁▁▁▁▁▁▁▁█
vue-router.full	58.99 KiB	+37 B (+0.06%)	58.86 KiB	168.80 KiB	52.88 KiB	▁▁▁▁▁▁▁▁▁▁▁█
react-start.minimal	101.95 KiB	+41 B (+0.04%)	101.82 KiB	322.12 KiB	88.14 KiB	▁▁▁▂▂▂▄▄▄▄▄█
react-start.deferred-hydration	102.69 KiB	+41 B (+0.04%)	101.84 KiB	323.50 KiB	88.98 KiB	▁▁▂▂▂▂▅▅▅▅▅█
react-start.full	105.36 KiB	+44 B (+0.04%)	105.22 KiB	332.05 KiB	91.25 KiB	▆▆▁▁▁▁▅▅▅▅▅█
react-start.rsbuild.minimal	99.67 KiB	+38 B (+0.04%)	99.50 KiB	316.56 KiB	85.76 KiB	▂▂▁▂▂▂▅▅▅▅▅█
react-start.rsbuild.minimal-iife	100.07 KiB	+33 B (+0.03%)	99.90 KiB	317.50 KiB	86.17 KiB	▂▂▁▂▂▂▅▅▅▅▅█
react-start.rsbuild.full	102.89 KiB	+35 B (+0.03%)	102.72 KiB	326.62 KiB	88.50 KiB	██▁▁▁▁▅▅▅▅▅█
solid-start.minimal	49.64 KiB	+41 B (+0.08%)	49.51 KiB	152.07 KiB	43.77 KiB	▂▂▂▂▁▁▁▁▁▁▁█
solid-start.deferred-hydration	52.90 KiB	+40 B (+0.07%)	49.57 KiB	160.11 KiB	46.81 KiB	▁▁▁▂▁▁▁▁▁▁▁█
solid-start.full	55.45 KiB	+47 B (+0.08%)	55.31 KiB	169.11 KiB	48.92 KiB	▂▂▂▃▁▁▁▁▁▁▁█
vue-start.minimal	71.07 KiB	+52 B (+0.07%)	70.94 KiB	207.19 KiB	62.89 KiB	▁▁▁▂▂▂▂▂▂▂▂█
vue-start.full	75.06 KiB	+47 B (+0.06%)	74.93 KiB	219.82 KiB	66.35 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-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-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 91b3196

[codspeed-hq]

Merging this PR will improve performance by 5.07%

⚠️ 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

⚡ 3 improved benchmarks
✅ 93 untouched benchmarks

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	Simulation	client-side navigation loop (vue)	85.2 ms	79 ms	+7.78%
⚡	Simulation	ssr request loop (react)	81.1 ms	77.9 ms	+4.17%
⚡	Simulation	client-side navigation loop (solid)	116.9 ms	113.2 ms	+3.33%

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/router-core-lightweight-cache (91b3196) with main (36ed574)}