fix(router-core): skip scroll restoration setup when disabled

[schiller-manuel]

fixes #7472

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Fixed scroll restoration to only initialize listeners when scroll restoration is enabled in the browser, preventing unnecessary listener installation and improving performance.

[coderabbitai]

Complex PR? Review this PR in Change Stack to move by importance, not file order.

📝 Walkthrough

Walkthrough

Scroll state management is refactored from separate boolean flags into a structured _scroll object, and scroll restoration listener setup is now guarded behind a conditional check to prevent initialization in non-browser or disabled environments.

Changes

Scroll restoration conditional setup

Layer / File(s)	Summary
Scroll state structure in RouterCore packages/router-core/src/router.ts	RouterCore replaces resetNextScroll, isScrollRestoring, and isScrollRestorationSetup boolean fields with a unified _scroll object initialized with next: true, and updates commitLocation to set this._scroll.next from next.resetScroll.
Scroll restoration conditional setup and listener registration packages/router-core/src/scroll-restoration.ts	setupScrollRestoration now computes shouldSetupScrollRestoration and registers event listeners only when scroll restoration is enabled, guarding history.scrollRestoration = 'manual' and the pagehide, scroll, and onBeforeLoad listeners behind that condition. State checks throughout callbacks and merge logic switch from router.isScrollRestoring to scroll.restoring.
Scroll restoration enabled/disabled test coverage packages/router-core/tests/scroll-restoration.test.ts	Test suite verifies that when scrollRestoration: true, the internal scroll state reflects restoration being active, window.history.scrollRestoration is set to 'manual', and expected event listeners are registered; and when scrollRestoration is omitted or false, restoration setup does not occur and window.history.scrollRestoration remains 'auto'.
Documentation and devtools property filter update .changeset/fix-disabled-scroll-restoration.md, packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx	Changeset documents the fix to prevent scroll restoration listener installation when disabled. Devtools explorer exclusion list is updated to filter out the new _scroll property and remove previously excluded deprecated fields.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

package: router-core

Poem

🐰 Scroll state once scattered, now neatly bound,
Listeners wake only when restoration's found,
jsdom and Node can breathe once more,
No bare globals to break the store!
Tests confirm both paths now shine—
A fix that's elegant, secure, and fine. 🎯

🚥 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 'fix(router-core): skip scroll restoration setup when disabled' clearly describes the main change—refactoring scroll restoration to avoid setup when disabled, which directly addresses the linked issue #7472 about bare browser globals breaking non-browser environments.
Linked Issues check	✅ Passed	The PR refactors scroll restoration state into a structured object and adds guards to prevent setup when disabled, ensuring qualified access (window.addEventListener) rather than bare globals, which fully addresses issue #7472's regression where bare globals crashed router construction in Node+jsdom environments.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing scroll restoration: the changeset documentation, router state refactoring, scroll-restoration.ts guarding, comprehensive test coverage, and devtools update to track the new _scroll field. No unrelated modifications detected.

_{✏️ 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 fix-7472

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 93895cc

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

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

---

☁️ Nx Cloud last updated this comment at 2026-06-06 09:30:45 UTC

[github-actions]

🚀 Changeset Version Preview

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

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.171.12 → 1.171.13	Changeset
@tanstack/react-router	1.170.14 → 1.170.15	Dependent
@tanstack/react-start	1.168.23 → 1.168.24	Dependent
@tanstack/react-start-client	1.168.11 → 1.168.12	Dependent
@tanstack/react-start-rsc	0.1.22 → 0.1.23	Dependent
@tanstack/react-start-server	1.167.17 → 1.167.18	Dependent
@tanstack/router-cli	1.167.16 → 1.167.17	Dependent
@tanstack/router-generator	1.167.16 → 1.167.17	Dependent
@tanstack/router-plugin	1.168.17 → 1.168.18	Dependent
@tanstack/router-vite-plugin	1.167.17 → 1.167.18	Dependent
@tanstack/solid-router	1.170.14 → 1.170.15	Dependent
@tanstack/solid-start	1.168.23 → 1.168.24	Dependent
@tanstack/solid-start-client	1.168.11 → 1.168.12	Dependent
@tanstack/solid-start-server	1.167.17 → 1.167.18	Dependent
@tanstack/start-client-core	1.170.10 → 1.170.11	Dependent
@tanstack/start-plugin-core	1.171.15 → 1.171.16	Dependent
@tanstack/start-server-core	1.169.12 → 1.169.13	Dependent
@tanstack/start-static-server-functions	1.167.15 → 1.167.16	Dependent
@tanstack/start-storage-context	1.167.14 → 1.167.15	Dependent
@tanstack/vue-router	1.170.14 → 1.170.15	Dependent
@tanstack/vue-start	1.168.22 → 1.168.23	Dependent
@tanstack/vue-start-client	1.167.15 → 1.167.16	Dependent
@tanstack/vue-start-server	1.167.17 → 1.167.18	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: a0b4b53237e2
• Measured at: 2026-06-06T09:21:47.749Z
• Baseline source: history:996b9bee381c
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.25 KiB	-12 B (-0.01%)	87.11 KiB	273.66 KiB	75.97 KiB	▁▁▁▁▁▆▆▆███▆
react-router.full	91.08 KiB	-8 B (-0.01%)	90.94 KiB	286.05 KiB	79.21 KiB	▁▁▁▁▁▇▇▇████
solid-router.minimal	35.49 KiB	+5 B (+0.01%)	35.36 KiB	105.96 KiB	32.00 KiB	▁▁▁▁▁▅▅▅▇▇▇█
solid-router.full	40.54 KiB	-10 B (-0.02%)	40.41 KiB	121.17 KiB	36.49 KiB	▁▁▁▁▁▇▇▇████
vue-router.minimal	52.97 KiB	-1 B (-0.00%)	52.84 KiB	149.97 KiB	47.65 KiB	▁▁▁▁▁▅▅▅████
vue-router.full	58.95 KiB	-4 B (-0.01%)	58.82 KiB	168.73 KiB	52.81 KiB	▁▁▁▁▁▇▇▇████
react-start.minimal	101.88 KiB	-4 B (-0.00%)	101.74 KiB	321.97 KiB	88.22 KiB	▁▁▁▁▁▆▆▆████
react-start.deferred-hydration	102.61 KiB	-8 B (-0.01%)	101.76 KiB	323.35 KiB	88.95 KiB	▁▁▁▁▁▆▆▆███▇
react-start.full	105.29 KiB	+1 B (+0.00%)	105.15 KiB	332.28 KiB	91.07 KiB	▁▁▁▁▁▄▄▄████
react-start.rsbuild.minimal	99.60 KiB	+8 B (+0.01%)	99.43 KiB	316.46 KiB	85.65 KiB	▁▁▁▁▁▄▄▄▇▇▇█
react-start.rsbuild.minimal-iife	100.00 KiB	+9 B (+0.01%)	99.83 KiB	317.39 KiB	86.08 KiB	▁▁▁▁▁▅▅▅▇▇▇█
react-start.rsbuild.full	102.86 KiB	+7 B (+0.01%)	102.68 KiB	326.85 KiB	88.43 KiB	▁▁▁▁▁▅▅▅▇▇▇█
solid-start.minimal	49.60 KiB	+8 B (+0.02%)	49.47 KiB	152.02 KiB	43.81 KiB	▁▁▁▁▁▅▅▅▇▇▇█
solid-start.deferred-hydration	52.86 KiB	+7 B (+0.01%)	49.53 KiB	160.06 KiB	46.77 KiB	▁▁▁▁▁▅▅▅▇▇▇█
solid-start.full	55.37 KiB	-10 B (-0.02%)	55.24 KiB	168.95 KiB	48.82 KiB	▁▁▁▁▁▅▅▅███▇
vue-start.minimal	71.01 KiB	-1 B (-0.00%)	70.89 KiB	207.11 KiB	62.92 KiB	▁▁▁▁▁▅▅▅████
vue-start.full	74.97 KiB	-7 B (-0.01%)	74.84 KiB	219.63 KiB	66.31 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.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

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

196-203: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use window-qualified browser APIs to fully avoid non-browser-global runtime crashes.

The new conditional setup is good, but this path still uses bare globals (history, addEventListener, scrollX/scrollY, scrollTo). In environments where these are not on globalThis, setup/navigation can still throw.

Suggested patch

-    history.scrollRestoration = 'manual'
+    window.history.scrollRestoration = 'manual'
@@
-    addEventListener('pagehide', () => {
+    window.addEventListener('pagehide', () => {
@@
-      setTrackedScrollEntry(windowScrollTarget, scrollX, scrollY)
+      setTrackedScrollEntry(windowScrollTarget, window.scrollX, window.scrollY)
@@
-              scrollTo({
+              window.scrollTo({
                 top: scrollY,
                 left: scrollX,
                 behavior,
               })
@@
-          scrollTo(scrollOptions)
+          window.scrollTo(scrollOptions)

Also applies to: 227-247, 330-347, 366-366

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/router-core/src/scroll-restoration.ts` around lines 196 - 203, The
handlers (e.g., onScroll) and related logic currently use bare browser globals
which can throw in non-browser global environments; update all usages to use
window-qualified APIs (e.g., window.history, window.addEventListener /
window.removeEventListener, window.scrollX / window.scrollY, window.scrollTo)
and ensure any references to history/scrollX/scrollY/scrollTo in functions like
onScroll, setTrackedScrollEntry, and other scroll-restoration handlers are
replaced with window.X equivalents so they safely no-op or throw only in true
browser contexts; apply the same change to the other affected blocks indicated
(~lines 227–247, 330–347, 366).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@packages/router-core/src/scroll-restoration.ts`:
- Around line 196-203: The handlers (e.g., onScroll) and related logic currently
use bare browser globals which can throw in non-browser global environments;
update all usages to use window-qualified APIs (e.g., window.history,
window.addEventListener / window.removeEventListener, window.scrollX /
window.scrollY, window.scrollTo) and ensure any references to
history/scrollX/scrollY/scrollTo in functions like onScroll,
setTrackedScrollEntry, and other scroll-restoration handlers are replaced with
window.X equivalents so they safely no-op or throw only in true browser
contexts; apply the same change to the other affected blocks indicated (~lines
227–247, 330–347, 366).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 79696389-ba37-4cf9-9e60-27486215b45f

📥 Commits

Reviewing files that changed from the base of the PR and between 996b9be and 93895cc.

📒 Files selected for processing (5)

• .changeset/fix-disabled-scroll-restoration.md
• packages/router-core/src/router.ts
• packages/router-core/src/scroll-restoration.ts
• packages/router-core/tests/scroll-restoration.test.ts
• packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx

[pkg-pr-new]

More templates

• 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-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/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 93895cc

[codspeed-hq]

Merging this PR will not alter performance

✅ 5 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing fix-7472 (93895cc) with main (996b9be)}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩