Skip to content

Fix React hydration mismatch (#418) in SSR context providers - #17641

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

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

Conversation

@posthog

@posthog posthog Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Changes

Several React context providers read browser-only state directly inside useState initializers (or in values that drive render output). Because Gatsby renders these pages on the server — where window, localStorage, window.__theme, and bootstrapped feature flags aren't available — the first client render diverged from the server HTML and triggered a hydration mismatch (minified React error #418). Error tracking showed this firing at massive scale across the marketing and docs site (4.6M+ occurrences / 234K users in 30 days), with a fresh "first observed" issue spawned per app-<hash>.js deploy.

The fix initializes the affected state to its SSR-equivalent default and moves the browser reads into post-mount effects (gated behind a mounted flag), so the first client render matches the server. The theme-init.js inline script still sets the visual theme/wallpaper on <body> outside React, so there's no theme flash.

Files touched:

  • src/context/App.tsx — isMobile, compact, siteSettings, the initial windows array (?windows=, ?contact=, and mobile-homepage cases now applied after mount), and the getKey feature-flag branch
  • src/components/Layout/context.tsx — fullWidthContent, hedgehogMode, compact
  • src/components/ReaderView/context/ReaderViewContext.tsx — backgroundImage, nav/ToC visibility
  • src/pages/product-toolkit.tsx — direct-to-eu-cloud flag used in the signup CTA URL

Why: React #418 is a hydration mismatch (client re-renders rather than a broken flow), so per-user severity is low, but the volume drowns out genuinely new errors in the inbox and adds minor layout-flash/SEO cost. Deferring browser-only reads to after mount is the standard fix.

Note

node_modules isn't installed in the authoring environment, so a full Gatsby build/type-check couldn't be run here. Changes were syntax-validated and reviewed against the existing types/patterns; please confirm via the Vercel preview that hydration warnings are gone.

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.

Several context providers read browser-only state (window size, iframe
detection, localStorage, window.__theme, and bootstrapped feature flags)
directly in useState initializers or in values that drive render output.
On Gatsby's server-rendered HTML these reads aren't available, so the first
client render diverged from the server and triggered a hydration mismatch
(minified React error #418) across marketing and docs pages.

Initialize the affected state to its SSR-equivalent default and move the
browser reads into post-mount effects (gated behind a `mounted` flag), so
the first client render matches the server. The theme-init inline script
still handles the visual theme/wallpaper on <body>, so there's no flash.

Covers App.tsx (isMobile, compact, siteSettings, initial windows, getKey
feature-flag branch), Layout/context.tsx (fullWidthContent, hedgehogMode,
compact), ReaderViewContext.tsx (backgroundImage, nav/ToC visibility), and
product-toolkit.tsx (direct-to-eu-cloud flag in the CTA URL).

Generated-By: PostHog Code
Task-Id: 269b629c-d42a-4015-b792-8be6f9edd2cc
@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 01:09AM

@github-actions

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

6.30 MiB (+0.7 KiB / +0.0%)

Eager graph (static-import closure per entrypoint)

Entrypoint Eager size Budget Modules
✅ app 29.33 MiB (+22.9 KiB / +0.1%) report-only 5729
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.1 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 470.3 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 352.3 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