refactor(router-core): remove cachedMatches from reactive store

[Sheraff]

Following the removal of pendingMatches (#6670), this PR also removes cachedMatches from the reactive store, making them effectively private and not part of the public API.

Summary by CodeRabbit

• Documentation

  • Updated documentation to clarify that cached route matches are internal to the router and no longer exposed in public router state.

• Refactor

  • Cached route matches migration: moved from public router state to internal management.
  • Removed cached matches display section from DevTools panel.

• Tests

  • Updated test expectations across router packages to reflect changes to internal caching behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR internalizes the cached route matches previously exposed on RouterState by moving the cachedMatches field from public state to a private cachedMatchesInternal cache within RouterCore. Documentation is updated to reflect this change, the core router implementation is refactored to use the internal cache, devtools UI displaying cached matches is removed, and test expectations for store update counts are adjusted across multiple framework implementations.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/router/api/router/RouterStateType.md, docs/router/api/router/RouterType.md, docs/router/api/router/useRouterStateHook.md	Added migration notes clarifying that cached route matches are now internal to the router and no longer exposed through RouterState or useRouterState.
Core Router Implementation packages/router-core/src/router.ts	Removed public cachedMatches field from RouterState. Added private field cachedMatchesInternal and private helper methods (setCachedMatchesInternal, updateCachedMatchesInternal, appendCachedMatchesInternal) to RouterCore. Updated all code paths that previously mutated state.cachedMatches to use the internal cache instead.
Router-Core Tests packages/router-core/tests/load.test.ts	Replaced assertions inspecting router.state.cachedMatches with getMatch() based assertions, preserving structural expectations without relying on the now-internal cache.
Store Update Test Adjustments packages/react-router/tests/store-updates-during-navigation.test.tsx, packages/solid-router/tests/store-updates-during-navigation.test.tsx, packages/vue-router/tests/store-updates-during-navigation.test.tsx	Reduced expected store update counts across navigation scenarios to reflect lower update frequency resulting from internal cache changes.
Router Devtools UI packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx, packages/router-devtools-core/src/useStyles.tsx	Removed cached matches display from the devtools panel. Removed cachedMatchesContainer style and updated active match status calculation to exclude cached match state, rendering only 'Pending' or 'Active' states.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• #6468: Both PRs modify RouterCore's matching internals and remove/relocate cached data from public RouterState.
• #4995: Both PRs adjust expected store update counts in store-updates-during-navigation tests across navigation scenarios.
• #6454: Both PRs modify react-router's store-updates test file by adjusting store update count assertions.

Suggested reviewers

• schiller-manuel
• nlynzaad

Poem

🐰 Cached matches tucked away so neat,
No longer on the public street,
Internal workings, out of sight,
The router hops with cleaner light!
Store updates dance to fresher time,
A refactored, private pantomime! ✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main objective of the changeset: removing cachedMatches from the reactive store by making it private/internal.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into refactor-router-core-remove-pending-from-store-2

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor-router-core-remove-cached-from-store

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

packages/router-core/src/router.ts (1)

2620-2622: Prefer pending/active matches before cached for defensive freshness.
If a match id ever exists in more than one bucket (e.g., during async updates), cached-first could return a stale entry.

♻️ Suggested ordering (defensive)

-    return (
-      this.cachedMatchesInternal.find(findFn) ??
-      this.pendingMatchesInternal?.find(findFn) ??
-      this.state.matches.find(findFn)
-    )
+    return (
+      this.pendingMatchesInternal?.find(findFn) ??
+      this.state.matches.find(findFn) ??
+      this.cachedMatchesInternal.find(findFn)
+    )

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 8dfbe98

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

---

☁️ Nx Cloud last updated this comment at 2026-02-15 17:48:40 UTC

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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-rsc
• 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-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/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6673

@tanstack/eslint-plugin-router

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

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6673

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6673

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6673

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6673

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6673

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6673

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6673

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6673

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6673

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6673

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6673

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6673

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6673

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6673

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6673

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6673

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6673

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6673

commit: 8dfbe98