feat: Export useHydrated hook with documentation

[daveycodez]

Overview

Exports the useHydrated hook for both React and Solid Router, making it publicly available for developers to use in their applications. Previously, this hook was only used internally by the ClientOnly component.

Changes

• ✅ Export useHydrated from @tanstack/react-router
• ✅ Export useHydrated from @tanstack/solid-router
• ✅ Add comprehensive documentation for both React and Solid versions
• ✅ Include usage examples showing hydration-dependent UI patterns

What is useHydrated?

A hook that returns a boolean (React) or accessor (Solid) indicating whether client-side JavaScript has been hydrated. This is useful for:

• Safely accessing browser-only APIs during render (Intl, localStorage, geolocation)
• Conditionally rendering content based on client-side data
• Avoiding hydration mismatches while providing sensible server-side fallbacks
• Fine-grained control over hydration-dependent behavior

Behavior

• During SSR: Returns false
• First client render: Returns false
• After hydration: Returns true (persistent)

Documentation

Added sections in both framework guides:

• docs/start/framework/react/guide/execution-model.md
• docs/start/framework/solid/guide/execution-model.md

Example Usage

React:

import { useHydrated } from '@tanstack/react-router'

function TimeZoneDisplay() {
  const hydrated = useHydrated()
  const timeZone = hydrated 
    ? Intl.DateTimeFormat().resolvedOptions().timeZone 
    : 'UTC'
  
  return <div>Your timezone: {timeZone}</div>
}

Solid:

import { useHydrated } from '@tanstack/solid-router'

function TimeZoneDisplay() {
  const hydrated = useHydrated()
  const timeZone = () => hydrated() 
    ? Intl.DateTimeFormat().resolvedOptions().timeZone 
    : 'UTC'
  
  return <div>Your timezone: {timeZone()}</div>
}

This pattern allows components to render safely on the server with a fallback value (UTC) and then show the actual client timezone after hydration, avoiding hydration mismatches.

Summary by CodeRabbit

• New Features

  • Exposed a hydration-status hook for React and Solid so apps can detect client hydration and adjust rendering.

• Documentation

  • Added framework guides with examples (TimeZone/conditional rendering) and notes on SSR/first-render vs post-hydration behavior.

• Chores

  • Public API surfaces updated to include the new hydration-status hook; no runtime behavior changes.

[coderabbitai]

Walkthrough

Exports the existing internal useHydrated hook from both React and Solid router packages and adds documentation pages showing its usage and behavior across SSR, first client render, and post-hydration renders.

Changes

Cohort / File(s)	Summary
React Router exports packages/react-router/src/ClientOnly.tsx, packages/react-router/src/index.tsx	Made useHydrated an exported symbol in ClientOnly.tsx and re-exported it from the package barrel (index.tsx). Implementation unchanged.
Solid Router exports packages/solid-router/src/ClientOnly.tsx, packages/solid-router/src/index.tsx	Made useHydrated an exported symbol in ClientOnly.tsx and re-exported it from the package barrel (index.tsx). Implementation unchanged.
Documentation docs/start/framework/react/guide/execution-model.md, docs/start/framework/solid/guide/execution-model.md	Added useHydrated documentation with usage examples and behavior notes: returns false on SSR and the first client render, true after hydration for subsequent renders.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Server
  participant Client
  participant useHydrated

  rect rgba(200,230,255,0.3)
    Note over Server,Client: Server-side render
    Server->>Client: HTML (SSR)\n(useHydrated = false)
  end

  rect rgba(255,245,200,0.3)
    Note over Client,useHydrated: First client render (pre-hydration)
    Client->>useHydrated: read()
    useHydrated-->>Client: false
  end

  rect rgba(200,255,210,0.3)
    Note over Client,useHydrated: Hydration completes
    Client->>useHydrated: subscription/hydrate event
    useHydrated-->>Client: true
  end

  Note over Client: Subsequent renders
  Client->>useHydrated: read()
  useHydrated-->>Client: true

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify the exported signatures and types for both packages and ensure barrel re-exports are correct.
• Confirm builds/type-checks and that no accidental API collisions occur.
• Quick review of the docs examples for accuracy and clarity.

Suggested reviewers

• schiller-manuel
• birkskyum
• brenelz

Poem

🐰 A little hook hops out to play,
False in the dark, then true in the day.
Server whispers hush, client wakes the tune,
Hydration dances under the moon,
Hooray — the rabbit shipped it soon! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "feat: Export useHydrated hook with documentation" directly and accurately reflects the main changes in the pull request. The PR makes the useHydrated hook a public API export in both React Router and Solid Router packages while adding comprehensive documentation and usage examples to the execution-model guides. The title is specific, concise, and clearly communicates the primary objective without being vague or off-topic. It uses conventional commit format appropriate for feature additions and covers both the export and documentation aspects of the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6fcdcd9 and 464faf6.

📒 Files selected for processing (2)

• docs/start/framework/react/guide/execution-model.md (1 hunks)
• docs/start/framework/solid/guide/execution-model.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/start/framework/solid/guide/execution-model.md
• docs/start/framework/react/guide/execution-model.md

---

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 and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 464faf6

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	⛔ Cancelled	14s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-10-27 18:54:45 UTC