refactor(react-router): useMatches skips useRef during SSR

[Sheraff]

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Improved structural sharing behavior in the useMatches hook during server-side rendering for better performance and consistency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2d7ecccc-1cc2-41ef-87ff-e6851a96119a

📥 Commits

Reviewing files that changed from the base of the PR and between 757d433 and 4c4e4e7.

📒 Files selected for processing (2)

• .changeset/four-carrots-post.md
• packages/react-router/src/Matches.tsx

---

📝 Walkthrough

Walkthrough

This PR refactors useMatches to defer the previousResult ref initialization to the client path only, eliminating unnecessary ref creation during SSR while preserving structural sharing behavior on the client. A Changeset entry documents the patch release.

Changes

SSR Structural Sharing Fix

Layer / File(s)	Summary
Move ref initialization to client path packages/react-router/src/Matches.tsx, .changeset/four-carrots-post.md	useMatches returns early on the server path, then creates previousResult ref only on the client path with an eslint-disable comment. Changeset documents the patch release noting that useMatches skips useRef during SSR for improved structural sharing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A ref hops away from the server's cold ground,
On client paths only, it can now be found,
Structural sharing still holds firm and true,
SSR runs faster—no refs to accrue! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ 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 accurately and concisely describes the main change: moving useRef initialization in useMatches to only occur on the client path, skipping it during SSR, which directly matches the code alterations in Matches.tsx.
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.

_{✏️ 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 react-router-use-matches-no-ref-in-ssr

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 4c4e4e7

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

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-07 11:09:23 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 4 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.15 → 1.170.16	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

[github-actions]

Bundle Size Benchmarks

• Commit: ab14fbd4b1c1
• Measured at: 2026-06-07T11:01:37.627Z
• Baseline source: history:757d43375fab
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.25 KiB	0 B (0.00%)	87.11 KiB	273.66 KiB	75.97 KiB	▁▆▆▆███▆▆▆▆
react-router.full	91.08 KiB	0 B (0.00%)	90.94 KiB	286.05 KiB	79.21 KiB	▁▇▇▇███████
solid-router.minimal	35.49 KiB	0 B (0.00%)	35.36 KiB	105.96 KiB	32.00 KiB	▁▅▅▅▇▇▇████
solid-router.full	40.54 KiB	0 B (0.00%)	40.41 KiB	121.17 KiB	36.49 KiB	▁▇▇▇███████
vue-router.minimal	52.97 KiB	0 B (0.00%)	52.84 KiB	149.97 KiB	47.65 KiB	▁▅▅▅███████
vue-router.full	58.95 KiB	0 B (0.00%)	58.82 KiB	168.73 KiB	52.81 KiB	▁▇▇▇███████
react-start.minimal	101.88 KiB	0 B (0.00%)	101.74 KiB	321.97 KiB	88.22 KiB	▁▆▆▆███████
react-start.deferred-hydration	102.61 KiB	0 B (0.00%)	101.76 KiB	323.35 KiB	88.95 KiB	▁▆▆▆███▇▇▇▇
react-start.full	105.33 KiB	0 B (0.00%)	105.20 KiB	332.40 KiB	91.13 KiB	▁▃▃▃▆▆▆▆▆██
react-start.rsbuild.minimal	99.60 KiB	0 B (0.00%)	99.43 KiB	316.46 KiB	85.65 KiB	▁▄▄▄▇▇▇████
react-start.rsbuild.minimal-iife	100.00 KiB	0 B (0.00%)	99.83 KiB	317.39 KiB	86.08 KiB	▁▅▅▅▇▇▇████
react-start.rsbuild.full	102.89 KiB	0 B (0.00%)	102.72 KiB	326.96 KiB	88.50 KiB	▁▃▃▃▅▅▅▅▅██
solid-start.minimal	49.60 KiB	0 B (0.00%)	49.47 KiB	152.02 KiB	43.81 KiB	▁▅▅▅▇▇▇████
solid-start.deferred-hydration	52.86 KiB	0 B (0.00%)	49.53 KiB	160.06 KiB	46.77 KiB	▁▅▅▅▇▇▇████
solid-start.full	55.41 KiB	0 B (0.00%)	55.28 KiB	169.07 KiB	48.79 KiB	▁▄▄▄▅▅▅▅▅██
vue-start.minimal	71.01 KiB	0 B (0.00%)	70.89 KiB	207.11 KiB	62.92 KiB	▁▅▅▅███████
vue-start.full	75.01 KiB	0 B (0.00%)	74.88 KiB	219.75 KiB	66.39 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-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-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/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 4c4e4e7

[codspeed-hq]

Merging this PR will not alter performance

✅ 4 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing react-router-use-matches-no-ref-in-ssr (4c4e4e7) with main (757d433)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩