fix: HMR: only invalidate router if match is existing and not cached

[schiller-manuel]

Summary by CodeRabbit

• Bug Fixes
  • Improved hot module replacement efficiency by conditionally invalidating routes only when a matching route exists, reducing unnecessary invalidations during development.

[coderabbitai]

Walkthrough

The router-plugin's hot module replacement logic is updated to conditionally invalidate routes. Instead of unconditionally calling router.invalidate(), the code now checks if a matching route exists in router.state.matches or router.state.pendingMatches before invalidating, using a filter function to identify the old route ID.

Changes

Cohort / File(s)	Summary
Core HMR Implementation packages/router-plugin/src/core/route-hmr-statement.ts	Adds conditional guard to router.invalidate() call using a filter function that checks for matching routes before invalidation.
Test Snapshots packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx, packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx, packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx	Update generated HMR code snapshots to reflect conditional invalidation logic with matching guard.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verification needed: Confirm that the conditional guard correctly identifies matching routes and doesn't skip invalidation for valid updates.
• Pattern consistency: Verify the same filter pattern is correctly applied across all test snapshots.

Possibly related PRs

• fix: route HMR handling #5710: Modifies the same route-hmr-statement logic and route invalidation behavior in the router-plugin.

Poem

🐰 A hop, a skip, a guarded check—
No more invalidation by wreck!
Only when routes match, we say—
Refresh the view the clever way! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "fix: HMR: only invalidate router if match is existing and not cached" is directly related to the main change across all modified files. The pull request replaces unconditional router invalidation with conditional invalidation that only executes when a matching route exists in the router state. The title accurately captures this core behavioral change, clearly indicating that invalidation is now guarded by a condition checking for existing matches. While the phrase "not cached" could be slightly more precise in terminology, it effectively conveys the intent that invalidation is skipped when no match is present.

✨ 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 hmr-invalidation

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3e32efb and 2913af1.

📒 Files selected for processing (4)

• packages/router-plugin/src/core/route-hmr-statement.ts (2 hunks)
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx (1 hunks)
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx (1 hunks)
• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript in strict mode with extensive type safety across the codebase

Files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/**

📄 CodeRabbit inference engine (AGENTS.md)

Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

Files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

packages/router-plugin/**

📄 CodeRabbit inference engine (AGENTS.md)

Use unplugin for universal bundler plugins in the router-plugin package

Files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

🧠 Learnings (7)

📓 Common learnings

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-09-23T17:36:12.598Z
Learning: Applies to packages/router-plugin/** : Use unplugin for universal bundler plugins in the router-plugin package

Learnt from: nlynzaad
Repo: TanStack/router PR: 5402
File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
Timestamp: 2025-10-08T08:11:47.088Z
Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

📚 Learning: 2025-10-08T08:11:47.088Z

Learnt from: nlynzaad
Repo: TanStack/router PR: 5402
File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
Timestamp: 2025-10-08T08:11:47.088Z
Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

📚 Learning: 2025-09-23T17:36:12.598Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-09-23T17:36:12.598Z
Learning: Applies to packages/{react-router,solid-router}/** : Implement React and Solid bindings/components only in packages/react-router/ and packages/solid-router/

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

📚 Learning: 2025-10-01T18:30:26.591Z

Learnt from: schiller-manuel
Repo: TanStack/router PR: 5330
File: packages/router-core/src/router.ts:2231-2245
Timestamp: 2025-10-01T18:30:26.591Z
Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

📚 Learning: 2025-09-23T17:36:12.598Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-09-23T17:36:12.598Z
Learning: Applies to packages/{router-devtools,*-router-devtools}/** : Keep router devtools packages in packages/router-devtools/ and packages/*-router-devtools/

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx

📚 Learning: 2025-09-23T17:36:12.598Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-09-23T17:36:12.598Z
Learning: Applies to packages/router-plugin/** : Use unplugin for universal bundler plugins in the router-plugin package

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx

📚 Learning: 2025-09-23T17:36:12.598Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-09-23T17:36:12.598Z
Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

Applied to files:

• packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
• packages/router-plugin/src/core/route-hmr-statement.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Test
• GitHub Check: Preview

🔇 Additional comments (5)

packages/router-plugin/src/core/route-hmr-statement.ts (2)

2-2: LGTM! Type import addition for filter function.

The AnyRouteMatch type is correctly imported and used for type-safe filter function definition.

---

29-35: LGTM! Conditional invalidation prevents unnecessary updates.

The guarded invalidation correctly checks whether the route is currently active before triggering an invalidation. The optional chaining on pendingMatches properly handles the case when it's undefined.

packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx (1)

27-32: Test snapshot correctly reflects the new HMR pattern.

The generated code properly implements conditional invalidation, matching the core implementation in route-hmr-statement.ts.

packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx (1)

28-33: Test snapshot correctly reflects the React HMR implementation.

The generated code matches the expected pattern for conditional route invalidation during HMR.

packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx (1)

28-33: Test snapshot correctly reflects the React arrow function HMR pattern.

The generated code is consistent with the core implementation and other test fixtures.

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 2913af1

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

---

☁️ Nx Cloud last updated this comment at 2025-10-31 23:07:50 UTC

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• 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-streaming-file-based
• 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-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• 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-example-basic-supabase
• 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-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-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/arktype-adapter

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

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5713

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5713

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 2913af1