Skip to content

fix(router): apply preload delay to viewport links - #8044

Merged
Sheraff merged 7 commits into
mainfrom
fix/viewport-preload-delay
Aug 12, 2026
Merged

fix(router): apply preload delay to viewport links#8044
Sheraff merged 7 commits into
mainfrom
fix/viewport-preload-delay

Conversation

@Sheraff

@Sheraff Sheraff commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Fixes #8029

Summary

  • apply preloadDelay to viewport link preloading in the React, Solid, and Vue adapters
  • cancel delayed viewport preloads when links leave the viewport, observation stops, or link options change
  • key viewport timers by stable per-link refs so observer callback identity changes cannot orphan pending work
  • use the latest queued observer entry so brief exit/re-entry cycles delivered in one callback retain the existing delay
  • inline the fixed { rootMargin: "100px" } configuration inside each adapter observer utility and remove its options parameter
  • share delayed viewport and intent scheduling while preserving immediate touch preloads and cancelable focus/hover intent
  • deduplicate repeated viewport observer notifications and document the updated behavior
  • add React regression coverage for changing destinations while a viewport preload is pending
  • add a patch changeset for all three router adapters

Testing

  • pnpm nx run-many --target=test:unit --projects=@tanstack/react-router,@tanstack/solid-router,@tanstack/vue-router
  • pnpm nx run-many --target=test:types --projects=@tanstack/router-core,@tanstack/react-router,@tanstack/solid-router,@tanstack/vue-router
  • pnpm nx run-many --target=test:eslint --projects=@tanstack/router-core,@tanstack/react-router,@tanstack/solid-router,@tanstack/vue-router
  • full 17-scenario bundle-size build

Bundle Size

Affected gzip fixtures remain effectively flat versus the base commit:

  • React Router minimal/full: -2 B / -9 B
  • Solid Router minimal/full: +5 B / +3 B
  • Vue Router minimal/full: 0 B / -10 B

Summary by CodeRabbit

New Features

  • Link preloading now supports configurable delays for viewport, focus, and hover triggers across React, Solid, and Vue routers.
  • Touch-based intent preloading remains immediate.
  • Duplicate preload requests are consolidated.

Bug Fixes

  • Pending preloads are cancelled when links leave the viewport or interactions end.
  • Disabled, external, and document-reload links no longer trigger preloading.

Documentation

  • Clarified preload timing, cancellation, and trigger behavior in router guides and API references.

@nx-cloud

nx-cloud Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

View your CI Pipeline Execution ↗ for commit dddc18d

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

☁️ Nx Cloud last updated this comment at 2026-08-12 07:16:08 UTC

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Changeset Version Preview

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

🟩 Patch bumps

Package Version Reason
@tanstack/react-router 1.170.25 → 1.170.26 Changeset
@tanstack/router-core 1.171.21 → 1.171.22 Changeset
@tanstack/solid-router 1.170.24 → 1.170.25 Changeset
@tanstack/vue-router 1.170.23 → 1.170.24 Changeset
@tanstack/react-start 1.168.42 → 1.168.43 Dependent
@tanstack/react-start-client 1.168.23 → 1.168.24 Dependent
@tanstack/react-start-rsc 0.1.41 → 0.1.42 Dependent
@tanstack/react-start-server 1.167.30 → 1.167.31 Dependent
@tanstack/router-cli 1.167.27 → 1.167.28 Dependent
@tanstack/router-generator 1.167.27 → 1.167.28 Dependent
@tanstack/router-plugin 1.168.29 → 1.168.30 Dependent
@tanstack/router-vite-plugin 1.167.29 → 1.167.30 Dependent
@tanstack/solid-start 1.168.41 → 1.168.42 Dependent
@tanstack/solid-start-client 1.168.23 → 1.168.24 Dependent
@tanstack/solid-start-server 1.167.30 → 1.167.31 Dependent
@tanstack/start-client-core 1.170.21 → 1.170.22 Dependent
@tanstack/start-plugin-core 1.171.33 → 1.171.34 Dependent
@tanstack/start-server-core 1.169.25 → 1.169.26 Dependent
@tanstack/start-static-server-functions 1.167.26 → 1.167.27 Dependent
@tanstack/start-storage-context 1.167.23 → 1.167.24 Dependent
@tanstack/vue-start 1.168.40 → 1.168.41 Dependent
@tanstack/vue-start-client 1.167.26 → 1.167.27 Dependent
@tanstack/vue-start-server 1.167.30 → 1.167.31 Dependent

@coderabbitai

coderabbitai Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The React, Solid, and Vue routers now delay viewport preloading with preloadDelay. Shared scheduling handles intent and viewport events, cancellation, duplicate suppression, and disabled links. Tests and documentation cover the updated behavior.

Changes

Link preloading

Layer / File(s) Summary
Shared preload scheduling
packages/react-router/src/link.tsx, packages/solid-router/src/link.tsx, packages/vue-router/src/link.tsx
The routers use enqueuePreload for viewport and intent events. Delayed work is cancelled on leave, duplicate timers are suppressed, disabled links do not preload, and touch intent remains immediate.
Observer handling and test control
packages/*-router/src/utils.ts, packages/*-router/tests/link.test.tsx, packages/*-router/tests/utils.ts
Observer utilities use a fixed root margin and dispatch the last entry. Observer mocks expose callbacks for direct simulation. Tests cover delay timing, intersection filtering, cancellation, duplicate events, and brief hover interactions.
Preload delay contracts and release metadata
packages/router-core/src/*, docs/router/api/router/*, docs/router/guide/*, .changeset/tidy-links-wait.md
Documentation describes delayed focus, hover, and viewport preloading, immediate touch intent preloading, cancellation behavior, and the related patch releases.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.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
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.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely describes applying preload delay to viewport links, which is the main change in the pull request.
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/viewport-preload-delay

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

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

Bundle Size Benchmarks

  • Commit: 88f982c33d34
  • Measured at: 2026-08-12T07:04:44.634Z
  • Baseline source: history:7e93431ae9ff
  • Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario Current (gzip) Delta vs baseline Initial gzip Raw Brotli Trend
react-router.minimal 83.91 KiB -4 B (-0.00%) 83.78 KiB 262.65 KiB 73.12 KiB ██▁▁▁▁▁▁▁▁▁▁
react-router.full 87.42 KiB -6 B (-0.01%) 87.28 KiB 274.36 KiB 76.17 KiB ██▁▁▁▁▁▁▁▁▁▁
solid-router.minimal 33.24 KiB +2 B (+0.01%) 33.11 KiB 96.46 KiB 30.03 KiB ██▁▁▁▁▁▁▁▁▁▁
solid-router.full 38.06 KiB -3 B (-0.01%) 37.94 KiB 111.09 KiB 34.29 KiB ██▁▁▁▁▁▁▁▁▁▁
vue-router.minimal 49.51 KiB -7 B (-0.01%) 49.39 KiB 138.25 KiB 44.71 KiB ██▁▁▁▁▁▁▁▁▁▁
vue-router.full 55.08 KiB -20 B (-0.04%) 54.96 KiB 156.43 KiB 49.56 KiB ██▁▁▁▁▁▁▁▁▁▁
react-start.minimal 96.75 KiB -3 B (-0.00%) 96.61 KiB 304.86 KiB 83.95 KiB ██▁▁▁▁▁▁▁▁▁▁
react-start.deferred-hydration 97.46 KiB -13 B (-0.01%) 96.62 KiB 306.22 KiB 84.44 KiB ██▁▁▁▁▁▁▁▁▁▁
react-start.full 99.91 KiB -9 B (-0.01%) 99.77 KiB 314.58 KiB 86.61 KiB ██▁▁▁▁▁▁▁▁▁▁
react-start.rsbuild.minimal 100.05 KiB -15 B (-0.01%) 99.88 KiB 315.29 KiB 86.29 KiB ▁▁▁▁▆██████▆
react-start.rsbuild.minimal-iife 100.45 KiB -15 B (-0.01%) 100.29 KiB 316.22 KiB 86.65 KiB ▁▁▁▁▅██████▆
react-start.rsbuild.full 103.38 KiB -12 B (-0.01%) 103.21 KiB 325.38 KiB 89.01 KiB ▁▁▁▁▅██████▇
solid-start.deferred-hydration 49.10 KiB +16 B (+0.03%) 45.96 KiB 144.98 KiB 43.69 KiB ██▁▁▁▁▁▁▁▁▁▁
solid-start.full 51.10 KiB +13 B (+0.02%) 50.98 KiB 152.91 KiB 45.28 KiB ██▁▁▁▁▁▁▁▁▁▁
vue-start.minimal 65.54 KiB -2 B (-0.00%) 65.41 KiB 189.07 KiB 58.37 KiB ██▁▁▁▁▁▁▁▁▁▁
vue-start.full 69.36 KiB -3 B (-0.00%) 69.24 KiB 201.35 KiB 61.60 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

pkg-pr-new Bot commented Aug 11, 2026

Copy link
Copy Markdown
More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: dddc18d

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@packages/react-router/src/link.tsx`:
- Around line 648-653: Ensure delayed preload timers recheck current eligibility
before invoking doPreload: in packages/react-router/src/link.tsx (648-653),
store the latest eligible preload mode in a ref or cancel timers when
eligibility changes; in packages/solid-router/src/link.tsx (279-285),
re-evaluate preload(); and in packages/vue-router/src/link.tsx (275-281),
re-evaluate preload.value. Disabled links and links with reloadDocument enabled
must not preload.
- Line 738: Wrap the return in the touch-intent preload condition with curly
braces in the relevant link logic: update packages/react-router/src/link.tsx at
lines 738-738, packages/solid-router/src/link.tsx at lines 373-373, and
packages/vue-router/src/link.tsx at lines 347-347, preserving the existing
condition and return behavior.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2431d791-7134-4f46-bd10-bc9d4dc2850c

📥 Commits

Reviewing files that changed from the base of the PR and between 7e93431 and d44878d.

📒 Files selected for processing (16)
  • .changeset/tidy-links-wait.md
  • docs/router/api/router/LinkOptionsType.md
  • docs/router/api/router/RouterOptionsType.md
  • docs/router/guide/navigation.md
  • docs/router/guide/preloading.md
  • packages/react-router/src/link.tsx
  • packages/react-router/tests/link.test.tsx
  • packages/react-router/tests/utils.ts
  • packages/router-core/src/link.ts
  • packages/router-core/src/router.ts
  • packages/solid-router/src/link.tsx
  • packages/solid-router/tests/link.test.tsx
  • packages/solid-router/tests/utils.ts
  • packages/vue-router/src/link.tsx
  • packages/vue-router/tests/link.test.tsx
  • packages/vue-router/tests/utils.ts

Comment thread packages/react-router/src/link.tsx
Comment thread packages/react-router/src/link.tsx
@codspeed-hq

codspeed-hq Bot commented Aug 11, 2026

Copy link
Copy Markdown

Merging this PR will degrade performance by 6.47%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 3 improved benchmarks
❌ 7 (👁 7) regressed benchmarks
✅ 170 untouched benchmarks

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Memory mem server error-paths not-found (vue) 777.5 KB 481.3 KB +61.54%
Memory mem server error-paths not-found (react) 414.1 KB 397.3 KB +4.22%
Memory mem server error-paths error (react) 1,020.9 KB 989 KB +3.22%
👁 Memory mem server error-paths redirect (vue) 405.6 KB 421.3 KB -3.72%
👁 Memory mem server error-paths not-found (solid) 569.9 KB 783.9 KB -27.29%
👁 Memory mem server error-paths redirect (solid) 379.9 KB 392.4 KB -3.19%
👁 Memory mem server peak-large-page (react) 1.2 MB 2.3 MB -49.99%
👁 Memory mem client preload-churn (vue) 759.1 KB 818.6 KB -7.27%
👁 Memory mem client unique-location-churn (vue) 1.3 MB 1.3 MB -3.05%
👁 Memory mem client navigation-churn (solid) 693.2 KB 716.8 KB -3.29%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.


Comparing fix/viewport-preload-delay (dddc18d) with main (7e93431)

Open in CodSpeed

nx-cloud[bot]

This comment was marked as outdated.

@nx-cloud nx-cloud Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud has identified a possible root cause for your failed CI:

We identified that this failure is unrelated to the PR's changes, which are scoped to viewport preload delay logic in the router adapters. The tanstack-solid-start-e2e-basic-cloudflare test fails because the Cloudflare Workers runtime is not active during vite preview, preventing the expected UI element from rendering — a pre-existing environment configuration issue. No changes to this PR are required to resolve it.

No code changes were suggested for this issue.

Trigger a rerun:

Rerun CI

Nx Cloud View detailed reasoning on Nx Cloud ↗


🎓 Learn more about Self-Healing CI on nx.dev

@Sheraff
Sheraff merged commit aa10b65 into main Aug 12, 2026
26 checks passed
@Sheraff
Sheraff deleted the fix/viewport-preload-delay branch August 12, 2026 07:52
@github-actions github-actions Bot mentioned this pull request Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant