fix: Fix Hydrate re-exports to avoid circular HMR updates

[schiller-manuel]

Summary by CodeRabbit

• Bug Fixes
  • Resolved circular import issues affecting hydration initialization in React Start and Solid Start packages by restructuring module exports
• New Features
  • Hydrate and related utilities are now available through dedicated subpath imports for more granular module loading

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR restructures React and Solid Start packages to export Hydrate from dedicated subpaths rather than main client barrels. Both client packages add ./Hydrate subpath exports to package.json, update build configs, and remove Hydrate re-exports from their main barrels. Root packages then source Hydrate re-exports from these subpaths instead, with documentation explaining this prevents circular imports and HMR issues from client-side side effects.

Changes

Hydrate Subpath Restructuring

Layer / File(s)	Summary
React Start Client Hydrate Subpath packages/react-start-client/package.json, packages/react-start-client/vite.config.ts, packages/react-start-client/src/index.tsx	React client package exposes ./Hydrate as a new subpath export, updates vite config to include ./src/Hydrate.tsx as a separate build entry, and removes Hydrate and related types from the main barrel.
React Start Root Hydration Imports packages/react-start/src/index.ts	React root package updates Hydrate and type re-exports to source from @tanstack/react-start-client/Hydrate subpath with comments explaining circular import avoidance.
Solid Start Client Hydrate Subpath packages/solid-start-client/package.json, packages/solid-start-client/src/index.tsx	Solid client package adds ./Hydrate subpath export and removes Hydrate and related types from the main barrel, exposing only StartClient and hydrateStart.
Solid Start Root Hydration Imports packages/solid-start/src/index.ts	Solid root package updates Hydrate and type re-exports to source from @tanstack/solid-start-client/Hydrate subpath with inline documentation.
Release Documentation .changeset/fair-llamas-hydrate.md	Changeset entry documents patch version bumps and records the behavioral change of importing Hydrate from hydration-only subpaths.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested labels

package: react-start, package: solid-start

Poem

🐰 A path emerges, clean and bright,
Hydrate flows where side effects aren't tight,
React and Solid, hand in hand,
Root imports stand on firmer land,
No circles spin, no HMR flies—
Just subpaths leading to the skies!

🚥 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 change: restructuring Hydrate re-exports across four TanStack Start packages to use subpath imports instead of barrel imports, which prevents circular HMR dependencies.
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.

_{✏️ 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-hydrate-circular

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit aff3daa

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

---

☁️ Nx Cloud last updated this comment at 2026-05-26 19:49:01 UTC

[github-actions]

🚀 Changeset Version Preview

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

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-start	1.168.13 → 1.168.14	Changeset
@tanstack/react-start-client	1.168.4 → 1.168.5	Changeset
@tanstack/solid-start	1.168.13 → 1.168.14	Changeset
@tanstack/solid-start-client	1.168.4 → 1.168.5	Changeset

[github-actions]

Bundle Size Benchmarks

• Commit: 25eff35f39f6
• Measured at: 2026-05-26T19:34:05.171Z
• Baseline source: history:eb830eaa457c
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.30 KiB	0 B (0.00%)	87.16 KiB	274.03 KiB	75.92 KiB	▃▃▃▁▁▁▁████
react-router.full	90.75 KiB	0 B (0.00%)	90.61 KiB	285.39 KiB	78.80 KiB	█████▁▁▂▂▂▂
solid-router.minimal	35.53 KiB	0 B (0.00%)	35.41 KiB	106.33 KiB	32.01 KiB	▁▁▁▆▆▆▆████
solid-router.full	40.23 KiB	0 B (0.00%)	40.11 KiB	120.52 KiB	36.19 KiB	▇▇▇██▂▂▁▁▁▁
vue-router.minimal	53.02 KiB	0 B (0.00%)	52.89 KiB	150.35 KiB	47.56 KiB	███████▁▁▁▁
vue-router.full	58.65 KiB	0 B (0.00%)	58.52 KiB	168.08 KiB	52.55 KiB	▁▁▁▁▁██▅▅▅▅
react-start.minimal	101.93 KiB	0 B (0.00%)	101.79 KiB	322.35 KiB	88.25 KiB	█████▁▁▁▁▁▁
react-start.deferred-hydration	102.66 KiB	0 B (0.00%)	101.81 KiB	323.72 KiB	88.82 KiB	█████▆▆▁▁▁▁
react-start.full	105.31 KiB	0 B (0.00%)	105.17 KiB	332.66 KiB	91.06 KiB	█████▁▁▁▁▁▁
react-start.rsbuild.minimal	99.61 KiB	0 B (0.00%)	99.44 KiB	316.79 KiB	85.73 KiB	█████▁▁▁▁▂▂
react-start.rsbuild.full	102.88 KiB	0 B (0.00%)	102.71 KiB	327.18 KiB	88.52 KiB	█████▁▁▁▁▁▁
solid-start.minimal	49.63 KiB	0 B (0.00%)	49.50 KiB	152.40 KiB	43.84 KiB	█████▁▁▁▁▁▁
solid-start.deferred-hydration	52.89 KiB	0 B (0.00%)	49.55 KiB	160.44 KiB	46.71 KiB	███████▁▁▁▁
solid-start.full	55.41 KiB	0 B (0.00%)	55.29 KiB	169.33 KiB	48.81 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]

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@7492

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: aff3daa

[coderabbitai]

🧹 Nitpick comments (1)

.changeset/fair-llamas-hydrate.md (1)

8-8: ⚡ Quick win

Enhance the changeset description for clarity.

The current description explains the technical solution but could be clearer about the motivation and user impact. Consider revising to include:

1. The problem being solved: The PR title mentions "circular HMR updates" but this isn't reflected in the changeset
2. User-facing impact: Whether users need to change their imports (especially for direct client package consumers)
3. What changed: More explicitly state that Hydrate is now exported from a dedicated subpath in client packages

📝 Suggested description improvement

-Avoid pulling the client hydration entry into root `@tanstack/react-start` and `@tanstack/solid-start` imports by re-exporting `Hydrate` from framework client Hydrate-only subpaths.
+Fix circular HMR updates by moving `Hydrate` exports to dedicated subpaths in client packages. 
+
+`Hydrate` is now exported from `@tanstack/react-start-client/Hydrate` and `@tanstack/solid-start-client/Hydrate` instead of the main client barrels. The root packages (`@tanstack/react-start` and `@tanstack/solid-start`) continue to re-export `Hydrate` from these subpaths, so users importing from root packages are unaffected.
+
+**Note**: If you import `Hydrate` directly from `@tanstack/react-start-client` or `@tanstack/solid-start-client`, update your imports to use the `/Hydrate` subpath.

🤖 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 @.changeset/fair-llamas-hydrate.md at line 8, Update the changeset text to
clearly state the problem (circular HMR updates), the user-facing impact, and
the specific API change: explain that to prevent circular HMR updates we moved
Hydrate export out of the root bundles and now re-export Hydrate from dedicated
client "Hydrate-only" subpaths in `@tanstack/react-start` and
`@tanstack/solid-start`; state whether consumers of the client packages must
update imports (e.g., import { Hydrate } from
"`@tanstack/react-start/client-hydrate`" or similar) or if existing root-package
imports remain compatible, and briefly note why this reduces bundle pull-in and
HMR loops.

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

Nitpick comments:
In @.changeset/fair-llamas-hydrate.md:
- Line 8: Update the changeset text to clearly state the problem (circular HMR
updates), the user-facing impact, and the specific API change: explain that to
prevent circular HMR updates we moved Hydrate export out of the root bundles and
now re-export Hydrate from dedicated client "Hydrate-only" subpaths in
`@tanstack/react-start` and `@tanstack/solid-start`; state whether consumers of the
client packages must update imports (e.g., import { Hydrate } from
"`@tanstack/react-start/client-hydrate`" or similar) or if existing root-package
imports remain compatible, and briefly note why this reduces bundle pull-in and
HMR loops.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14958f33-92df-4f2b-86a5-f57ff2f49cd1

📥 Commits

Reviewing files that changed from the base of the PR and between aee3661 and aff3daa.

📒 Files selected for processing (8)

• .changeset/fair-llamas-hydrate.md
• packages/react-start-client/package.json
• packages/react-start-client/src/index.tsx
• packages/react-start-client/vite.config.ts
• packages/react-start/src/index.ts
• packages/solid-start-client/package.json
• packages/solid-start-client/src/index.tsx
• packages/solid-start/src/index.ts

💤 Files with no reviewable changes (2)

• packages/react-start-client/src/index.tsx
• packages/solid-start-client/src/index.tsx

[codspeed-hq]

Merging this PR will not alter performance

✅ 5 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing fix-hydrate-circular (aff3daa) with main (eb830ea)²}

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

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