fix(router-core): propagate beforeLoad context to sub-route while its loader reloads in the background

[ulrichstark]

Fixes #7602

Summary by CodeRabbit

• Bug Fixes
  • Resolved an issue where context values set by parent routes were not propagated to child routes during background reloading. Child routes now maintain consistent access to parent-provided context values during all reload scenarios.

[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: e8f68a8c-ee7b-4da8-b3cc-86621f1fe0ae

📥 Commits

Reviewing files that changed from the base of the PR and between 96eca43 and f04a75c.

📒 Files selected for processing (6)

• .changeset/violet-poets-wait.md
• e2e/react-router/basic-file-based/src/routeTree.gen.ts
• e2e/react-router/basic-file-based/src/routes/context-propagation/index.tsx
• e2e/react-router/basic-file-based/src/routes/context-propagation/route.tsx
• e2e/react-router/basic-file-based/tests/context-propagation.spec.ts
• packages/router-core/src/load-matches.ts

---

📝 Walkthrough

Walkthrough

This PR fixes a bug where context values set by a parent route's beforeLoad hook are not available to a child route during background loader execution. The fix adds context synchronization in the background reload path, validated by new test routes and an E2E test.

Changes

Context Propagation in Background Reloads

Layer / File(s)	Summary
Background loader context synchronization packages/router-core/src/load-matches.ts	In the background reload branch of loadRouteMatch's handleLoader, syncMatchContext is called immediately after setting loaderIsRunningAsync = true, ensuring parent route context is propagated before the async loader executes.
Test route definitions and integration e2e/react-router/basic-file-based/src/routes/context-propagation/route.tsx, e2e/react-router/basic-file-based/src/routes/context-propagation/index.tsx, e2e/react-router/basic-file-based/src/routeTree.gen.ts, e2e/react-router/basic-file-based/tests/context-propagation.spec.ts	New file-based route pair: parent route /context-propagation exports context {number: 42} via beforeLoad; child route /context-propagation/ has staleTime: 0 and a 100ms-delayed loader, then renders the context value and a flag tracking whether context was ever undefined. Generated route tree wires both routes into the tree. Playwright E2E test navigates to the route, verifies context renders as 42 with no undefined observation, clicks Home, navigates back, and re-verifies the same result to ensure context is never unavailable during async loader execution.
Release documentation .changeset/violet-poets-wait.md	Changeset documents a patch version bump for @tanstack/router-core and describes the fix for context propagation during background loader reloads.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

package: router-core

Poem

🐰 A bunny fixed the missing thread,
When loaders run, the context's spread—
Parent whispers secrets true,
Child hears them before work's through! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: propagating beforeLoad context to sub-routes during background loader execution, which directly matches the primary code changes in load-matches.ts and the linked issue.
Linked Issues check	✅ Passed	The PR successfully addresses issue #7602 by synchronizing match context in load-matches.ts during background reloads, with corresponding test coverage validating that context values are properly propagated throughout the loader lifecycle.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing the context propagation issue: the core fix in load-matches.ts, generated route-tree updates, test routes, and e2e test are all scoped to validating and implementing the solution.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit f04a75c

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

---

☁️ Nx Cloud last updated this comment at 2026-06-11 14:16:39 UTC

[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-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@7603

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: f04a75c

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing ulrichstark:fix(router-core)--propagate-beforeLoad-context-to-sub-route-while-its-loader-reloads-in-the-background (f04a75c) with main (96eca43)}