Skip to content

Fix React hydration mismatch from client-only state in providers - #17673

Closed
posthog[bot] wants to merge 1 commit into
masterfrom
posthog-code/fix-hydration-mismatch-site-settings
Closed

posthog[bot] wants to merge 1 commit into
masterfrom
posthog-code/fix-hydration-mismatch-site-settings

Conversation

@posthog

@posthog posthog Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Changes

Users were hitting React hydration failures (#418 "Hydration failed…" and its recovery half #423 "…React recovered by client-rendering the entire root") that throw away the server-rendered HTML and re-render the whole page in the browser — a content flash and slower perceived load.

The root cause is render-affecting initial state computed from client-only sources while SSR falls back to static defaults, so the first client render doesn't match the server HTML:

  • src/context/App.tsx — getInitialSiteSettings read localStorage (siteSettings/lastReset), window.__theme, and window.innerWidth < 768, and isMobile was seeded from window.innerWidth. Any user with saved settings, on mobile, or in website ("boring") mode rendered a different tree than the server.
  • src/components/Layout/context.tsx — compact (window !== window.parent), fullWidthContent (localStorage), and hedgehogModeEnabled (localStorage) were read at render and exposed via context (all false under SSR), branching the tree for embeds and users with those settings.

The fix applies the standard Gatsby/SSR pattern: initialize this state to the SSR defaults so the first client render is identical on both sides, then reconcile the real values from localStorage/window in a useEffect after mount. Effects that legitimately need the live compact value (the docs-embed postMessage handshake) are left reading it directly, so embedding is unaffected. No suppressHydrationWarning — the trees genuinely match now.

Why: The #418 mismatch has 25,076 occurrences across 15,728 users since 2025-11-25, and each deploy mints a fresh #423 fingerprint as the recovery half. This removes the mismatch at the source rather than masking it.

Verification note: Verified with TypeScript type-check and Prettier, and by construction — both providers now produce a first client render identical to the SSR output. A full production-build hydration repro couldn't be run in this environment (incomplete dependency install — gatsby binary absent — plus a Node engine mismatch). Worth a check on the Vercel preview build before merge.

Checklist

  • I've read the docs and/or content style guides.
  • Words are spelled using American English
  • Use relative URLs for internal links
  • I've checked the pages added or changed in the Vercel preview build
  • If I moved a page, I added a redirect in vercel.json

Created with PostHog Code from an inbox report.

The App and Layout providers computed render-affecting initial state from
client-only sources (localStorage, window.innerWidth, window.__theme,
window !== window.parent), while SSR fell back to static defaults. Any user
with saved settings, on mobile, in website ("boring") mode, or in an embedded
docs iframe got a first client render that differed from the server HTML,
causing React #418 hydration mismatches and the #423 full-root client re-render
recovery (content flash, slower perceived load).

Initialize siteSettings, isMobile, and theme to the SSR defaults so the first
client render matches the server, then reconcile the real values in a useEffect
after mount. Do the same for the Layout provider's compact, fullWidthContent,
and hedgehogModeEnabled values by exposing the SSR defaults until a post-mount
hydrated flag flips. Effects that need the live compact value (docs-embed
postMessage handshake) are untouched.

paths:
- src/context/App.tsx
- src/components/Layout/context.tsx

Generated-By: PostHog Code
Task-Id: d6647b63-e0d7-49b2-a4fe-fc544f992124
@github-actions

github-actions Bot commented Jun 16, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Jun 16, 2026 08:41PM

@github-actions

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

6.25 MiB (+0.1 KiB / +0.0%)

Eager graph (static-import closure per entrypoint)

Entrypoint Eager size Budget Modules
✅ app 29.17 MiB (+2.2 KiB / +0.0%) report-only 5728
Largest modules in the app closure
Module Size
./node_modules/.pnpm/mapbox-gl@3.16.0/node_modules/mapbox-gl/dist/mapbox-gl.js 1619.1 KiB
./src/mdxGlobalComponents.js + 138 modules 868.2 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 710.0 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/lottie-web@5.13.0/node_modules/lottie-web/build/player/lottie.js 610.8 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./.cache/caches/gatsby-plugin-mdx/mdx-scopes-dir/31a094f140f119e73085d847ae81b99b.js + 2 modules 474.6 KiB
./node_modules/.pnpm/@codemirror+view@6.38.2/node_modules/@codemirror/view/dist/index.js 458.1 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.cjs.js 364.8 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./src/hooks/useCustomers.tsx + 54 modules 353.9 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./node_modules/.pnpm/jspdf@3.0.2/node_modules/jspdf/dist/jspdf.es.min.js 334.1 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js 281.9 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes.

@github-actions

Copy link
Copy Markdown
Contributor

This PR hasn't seen activity in two weeks! Should it be merged, closed, or further worked on? If you want to keep it open, please remove the stale label – otherwise this will be closed in another week. If you want to permanently keep it open, use the waiting label.

@github-actions github-actions Bot added the stale This pull request has been marked as stale and will be closed soon automatically label Jul 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

This PR was closed due to lack of activity. Feel free to reopen if it's still relevant.

@github-actions github-actions Bot closed this Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

stale This pull request has been marked as stale and will be closed soon automatically

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants