docs: align loader docs with lane rewrite

[Sheraff]

What

Updates the Router documentation and related Link option JSDoc to match the loader architecture merged in TanStack/router#7805:

• documents the preload cause and per-route preload behavior
• explains speculative terminal results from preloadRoute, including the boundary between settled results and shared in-flight outcomes
• distinguishes preload freshness, navigation freshness, and lazy cache retention/pruning
• describes shared loader flights and their abort-controller lifetime
• corrects invalidation coverage for committed, cached, and in-flight generations
• removes guarantees that preloadStaleTime: 0 always invokes loaders
• aligns route-option documentation with navigation-owned versus preload-owned retention

Two unrelated documentation fixes

These are the only two fixes in this PR that are not related to #7805:

1. Data mutation cache description — corrects the pre-existing claim that TanStack Router does not cache data and that loader data disappears as soon as a match unmounts.
2. Link preload option documentation — corrects the pre-existing duration wording, documents all four strategies, and clarifies that preloadDelay applies to focus and hover intent while touch intent preloads immediately.

Why

#7805 moved loading work into speculative lanes and shareable loader flights. Some docs still described the previous per-match lifecycle, so they gave incorrect guidance about preloads, errors, cancellation, invalidation, and cache freshness.

Impact

Documentation and JSDoc only. There are no runtime or release behavior changes.

Verification

• three independent source-code audits covered every changed documentation claim, followed by final spot checks after corrections
• targeted Prettier check for all changed Markdown and TypeScript files
• git diff --check
• affected ESLint targets passed
• affected type targets passed for 36 projects
• affected unit targets passed for 28 projects
• focused @tanstack/router-core preload/cache tests passed: 6 files, 121 tests, no type errors

Summary by CodeRabbit

• New Features

  • Added viewport- and render-based link preloading options alongside existing intent preloading.
  • Added route-level control to run speculative preloading without loading route data.
  • Expanded route lifecycle support for preload operations.

• Documentation

  • Clarified preload timing, cancellation, caching, retention, invalidation, error handling, and shared loader behavior.
  • Updated navigation, data-loading, mutation, and manual preloading guidance with revised examples and lifecycle details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b6c4ac7f-9b26-42e1-987a-56f513088cae

📥 Commits

Reviewing files that changed from the base of the PR and between 1d5c067 and f0d0a98.

📒 Files selected for processing (1)

• docs/router/guide/navigation.md

---

📝 Walkthrough

Walkthrough

The PR updates preload strategy documentation and clarifies speculative route lifecycles, loader sharing, cache retention, invalidation, abort signals, external caches, and manual preload error handling.

Changes

Preload and loader lifecycle

Layer / File(s)	Summary
Preload modes and intent behavior docs/router/api/router/LinkOptionsType.md, docs/router/guide/navigation.md, packages/router-core/src/link.ts	Documents viewport and render preload modes. Clarifies immediate touch preloading, delayed focus or hover preloading, and cancellation.
Speculative route lifecycle docs/router/api/router/RouteOptionsType.md, docs/router/api/router/RouterType.md	Documents the preload cause, speculative errors, the preload route option, loader reuse, and gcTime and preloadGcTime semantics.
Loader sharing and cache semantics docs/router/guide/data-loading.md, docs/router/guide/preloading.md	Clarifies shared loader work, abort signals, freshness, retention, invalidation, external-cache behavior, and preload reuse.
Invalidation and manual preload handling docs/router/guide/data-mutations.md, docs/router/guide/preloading.md	Documents invalidation and background revalidation. React and Solid examples inspect returned speculative matches for errors and not-found results.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: sajadtorkamani

🚥 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 summarizes the documentation updates for the loader lane rewrite.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/update-lane-loader-docs

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 1d5c067

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

---

☁️ Nx Cloud last updated this comment at 2026-08-04 20:19:07 UTC

[github-actions]

🚀 Changeset Version Preview

5 package(s) bumped directly, 23 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.18 → 1.170.19	Changeset
@tanstack/router-core	1.171.15 → 1.171.16	Changeset
@tanstack/router-devtools-core	1.168.0 → 1.168.1	Changeset
@tanstack/solid-router	1.170.18 → 1.170.19	Changeset
@tanstack/vue-router	1.170.17 → 1.170.18	Changeset
@tanstack/react-router-devtools	1.167.0 → 1.167.1	Dependent
@tanstack/react-start	1.168.35 → 1.168.36	Dependent
@tanstack/react-start-client	1.168.16 → 1.168.17	Dependent
@tanstack/react-start-rsc	0.1.34 → 0.1.35	Dependent
@tanstack/react-start-server	1.167.23 → 1.167.24	Dependent
@tanstack/router-cli	1.167.21 → 1.167.22	Dependent
@tanstack/router-devtools	1.167.0 → 1.167.1	Dependent
@tanstack/router-generator	1.167.21 → 1.167.22	Dependent
@tanstack/router-plugin	1.168.23 → 1.168.24	Dependent
@tanstack/router-vite-plugin	1.167.23 → 1.167.24	Dependent
@tanstack/solid-router-devtools	1.167.0 → 1.167.1	Dependent
@tanstack/solid-start	1.168.34 → 1.168.35	Dependent
@tanstack/solid-start-client	1.168.16 → 1.168.17	Dependent
@tanstack/solid-start-server	1.167.23 → 1.167.24	Dependent
@tanstack/start-client-core	1.170.14 → 1.170.15	Dependent
@tanstack/start-plugin-core	1.171.26 → 1.171.27	Dependent
@tanstack/start-server-core	1.169.18 → 1.169.19	Dependent
@tanstack/start-static-server-functions	1.167.19 → 1.167.20	Dependent
@tanstack/start-storage-context	1.167.17 → 1.167.18	Dependent
@tanstack/vue-router-devtools	1.167.0 → 1.167.1	Dependent
@tanstack/vue-start	1.168.33 → 1.168.34	Dependent
@tanstack/vue-start-client	1.167.19 → 1.167.20	Dependent
@tanstack/vue-start-server	1.167.23 → 1.167.24	Dependent

[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-rsbuild
• 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@7949

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: f0d0a98

[github-actions]

Bundle Size Benchmarks

This pull request does not affect bundle size in any measured scenario.

[codspeed-hq]

Merging this PR will degrade performance by 10.53%

⚠️ 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
❌ 4 (👁 1) regressed benchmarks
✅ 173 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server error-paths redirect (react)	188.3 KB	199.8 KB	-5.79%
❌	Simulation	ssr control-flow route headers (react)	60.2 ms	62.2 ms	-3.34%
❌	Simulation	ssr server-fn during document ssr (react)	63 ms	65.1 ms	-3.33%
⚡	Memory	mem server error-paths not-found (vue)	327.5 KB	314.3 KB	+4.19%
⚡	Simulation	ssr selective (solid)	72.9 ms	70.1 ms	+4%
⚡	Simulation	client-rewrites navigation loop (solid)	84.5 ms	81.3 ms	+3.96%
👁	Memory	mem server error-paths unmatched (react)	263.2 KB	569 KB	-53.74%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing agent/update-lane-loader-docs (f0d0a98) with main (a4942ff)}

[nx-cloud]

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 documentation and JSDoc only. The prerender task failed because the external API jsonplaceholder.typicode.com returned a 502 Bad Gateway during data fetching. Re-running the task once the external service recovers should resolve this.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/router/guide/navigation.md`:
- Around line 130-133: Update the “Link Preloading” section to document all
LinkOptions.preload strategies—false, intent, viewport, and render—and revise
its preloadDelay guidance to state that focus and hover intent use the delay
while touch intent preloads immediately, matching the nearby LinkOptions
documentation.

🪄 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: 0c5d1753-acf0-47a5-a572-9fc03a8150b0

📥 Commits

Reviewing files that changed from the base of the PR and between a4942ff and 1d5c067.

📒 Files selected for processing (8)

• docs/router/api/router/LinkOptionsType.md
• docs/router/api/router/RouteOptionsType.md
• docs/router/api/router/RouterType.md
• docs/router/guide/data-loading.md
• docs/router/guide/data-mutations.md
• docs/router/guide/navigation.md
• docs/router/guide/preloading.md
• packages/router-core/src/link.ts