docs(start): troubleshoot loader serialization failures by tannerlinsley · Pull Request #8395 · TanStack/router

tannerlinsley · 2026-09-12T04:25:49Z

🎯 Changes

Explain why a loader returning a plain function can work during browser navigation but fail on an SSR refresh, and show the data-only return value that fixes it. This adds troubleshooting to the existing hydration-errors guide.

A Router SSR regression exercises the failing function value and the accepted string result. A Start browser fixture verifies Date, Map, Set, BigInt, and undefined through server rendering, hydration, and client navigation. The navigation test also checks that the document stays loaded, and an interactive counter verifies hydration.

This complements #8162, which updates the serialization reference and documents adapters. It does not duplicate that reference edit. Related report: #7843.

Validation: 2 focused serializer tests and 8 browser cases across Vite/Rsbuild SSR/SPA passed. Required lint, type, and unit checks and formatting passed.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
I fully understand the code in this pull request.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Documentation
- Added guidance for diagnosing hydration failures that occur on page refresh but not during client navigation.
- Clarified server-side serialization requirements for loader data, including supported values and function handling.
- Explained why hydration-warning suppression does not resolve missing loader data.
Examples & Tests
- Added an interactive example demonstrating serialization of dates, maps, sets, bigints, and optional values.
- Added coverage for direct requests, hydration, client navigation, and interaction after loading serialized data.

nx-cloud · 2026-09-12T04:26:19Z

View your CI Pipeline Execution ↗ for commit 92bf3f7

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

☁️ Nx Cloud last updated this comment at 2026-09-12 04:36:17 UTC

coderabbitai · 2026-09-12T04:26:59Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 0727bc03-29a9-41bb-8684-02d061b07040

📥 Commits

Reviewing files that changed from the base of the PR and between 05422da and 92bf3f7.

📒 Files selected for processing (6)

docs/start/framework/react/guide/hydration-errors.md
e2e/react-start/basic/src/routeTree.gen.ts
e2e/react-start/basic/src/routes/__root.tsx
e2e/react-start/basic/src/routes/loader-serialization.tsx
e2e/react-start/basic/tests/loader-serialization.spec.ts
packages/router-core/tests/ssr-loader-serialization.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

Walkthrough

The change adds loader serialization guidance, a React Start example route, generated route wiring, and tests for SSR dehydration, direct requests, client navigation, hydration, and client interaction.

Changes

Loader serialization

Layer / File(s)	Summary
SSR serialization validation `packages/router-core/tests/ssr-loader-serialization.test.ts`	Tests cover string and function-valued loader data during server-router dehydration.
Serialized loader example and route wiring `e2e/react-start/basic/src/routes/loader-serialization.tsx`, `e2e/react-start/basic/src/routeTree.gen.ts`, `e2e/react-start/basic/src/routes/__root.tsx`, `e2e/react-start/basic/tests/loader-serialization.spec.ts`	Adds a route that renders `Date`, `Map`, `Set`, `BigInt`, and `undefined` loader values. The route is registered, linked from navigation, and tested through direct and client-side navigation.
Hydration troubleshooting guidance `docs/start/framework/react/guide/hydration-errors.md`	Documents non-serializable loader results, Server Functions, component-side formatting, and the limits of `suppressHydrationWarning`.

Priority: ⬇️ Low

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

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant Browser
  participant LoaderSerializationRoute
  participant ServerRouter
  participant LoaderSerializationComponent
  Browser->>LoaderSerializationRoute: request /loader-serialization
  LoaderSerializationRoute->>ServerRouter: load route data
  ServerRouter-->>LoaderSerializationRoute: serialize loader values
  LoaderSerializationRoute-->>LoaderSerializationComponent: provide loader data
  LoaderSerializationComponent-->>Browser: render values and client counter

Merge Risk: ⚪ Minimal · up to 92bf3

The new loader-serialization example, coverage, and guidance are consistent and ready to merge.

🚥 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%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 5 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: troubleshooting loader serialization failures in the Start hydration documentation.
Description check	✅ Passed	The description follows the required template, explains the motivation and changes, reports validation, completes the checklist, and identifies the work as docs/CI/dev-only with no changeset required.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 5 files. (1 skipped: 1 unsupported.)

Fix all pre-merge checks with AI

✨ 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 taren/start-loader-serialization

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 · 2026-09-12T04:27:36Z

🚀 Changeset Version Preview

3 package(s) bumped directly, 21 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
`@tanstack/history`	1.162.3 → 1.162.4	Changeset
`@tanstack/router-core`	1.171.29 → 1.171.30	Changeset
`@tanstack/start-server-core`	1.169.34 → 1.169.35	Changeset
`@tanstack/react-router`	1.170.35 → 1.170.36	Dependent
`@tanstack/react-start`	1.168.52 → 1.168.53	Dependent
`@tanstack/react-start-client`	1.168.33 → 1.168.34	Dependent
`@tanstack/react-start-rsc`	0.1.51 → 0.1.52	Dependent
`@tanstack/react-start-server`	1.167.40 → 1.167.41	Dependent
`@tanstack/router-cli`	1.167.35 → 1.167.36	Dependent
`@tanstack/router-generator`	1.167.35 → 1.167.36	Dependent
`@tanstack/router-plugin`	1.168.37 → 1.168.38	Dependent
`@tanstack/router-vite-plugin`	1.167.37 → 1.167.38	Dependent
`@tanstack/solid-router`	1.170.33 → 1.170.34	Dependent
`@tanstack/solid-start`	1.168.50 → 1.168.51	Dependent
`@tanstack/solid-start-client`	1.168.32 → 1.168.33	Dependent
`@tanstack/solid-start-server`	1.167.39 → 1.167.40	Dependent
`@tanstack/start-client-core`	1.170.29 → 1.170.30	Dependent
`@tanstack/start-plugin-core`	1.171.42 → 1.171.43	Dependent
`@tanstack/start-static-server-functions`	1.167.34 → 1.167.35	Dependent
`@tanstack/start-storage-context`	1.167.31 → 1.167.32	Dependent
`@tanstack/vue-router`	1.170.32 → 1.170.33	Dependent
`@tanstack/vue-start`	1.168.49 → 1.168.50	Dependent
`@tanstack/vue-start-client`	1.167.35 → 1.167.36	Dependent
`@tanstack/vue-start-server`	1.167.39 → 1.167.40	Dependent

github-actions · 2026-09-12T04:28:41Z

Bundle Size Benchmarks

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

pkg-pr-new · 2026-09-12T04:30:24Z

More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 92bf3f7

codspeed · 2026-09-12T04:43:55Z

Merging this PR will not alter performance

✅ 180 untouched benchmarks

_{Comparing taren/start-loader-serialization (92bf3f7) with main (e047e3f)¹}

No successful run was found on main (05422da) during the generation of this report, so e047e3f was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

docs(start): troubleshoot loader serialization failures

92bf3f7

github-actions Bot added documentation Everything documentation related package: router-core labels Sep 12, 2026

Navigation Menu

Uh oh!

docs(start): troubleshoot loader serialization failures - #8395

docs(start): troubleshoot loader serialization failures#8395
tannerlinsley wants to merge 1 commit into
mainfrom
taren/start-loader-serialization

tannerlinsley commented Sep 12, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

nx-cloud Bot commented Sep 12, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 12, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Sep 12, 2026

Uh oh!

github-actions Bot commented Sep 12, 2026

Uh oh!

pkg-pr-new Bot commented Sep 12, 2026

Uh oh!

codspeed Bot commented Sep 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

tannerlinsley commented Sep 12, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

nx-cloud Bot commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Sep 12, 2026

🚀 Changeset Version Preview

🟩 Patch bumps

Uh oh!

github-actions Bot commented Sep 12, 2026

Bundle Size Benchmarks

Uh oh!

pkg-pr-new Bot commented Sep 12, 2026

Uh oh!

codspeed Bot commented Sep 12, 2026

Merging this PR will not alter performance

Footnotes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

tannerlinsley commented Sep 12, 2026 •

edited by coderabbitai Bot

Loading

nx-cloud Bot commented Sep 12, 2026 •

edited

Loading

coderabbitai Bot commented Sep 12, 2026 •

edited

Loading