Skip to content

Fix React #418 hydration mismatch from client-only theme/settings - #17643

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

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

Conversation

@posthog

@posthog posthog Bot commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Changes

src/context/App.tsx initialized siteSettings (theme, colorMode, skinMode, wallpaper, experience) directly from window.__theme and localStorage inside the initial useState. Those sources don't exist during Gatsby SSR, so any user whose saved theme/skin/wallpaper/experience differed from the defaults produced a first client render that disagreed with the server-rendered HTML — triggering a recoverable React #418 hydration mismatch ("text content does not match server-rendered HTML") on nearly every page load.

This was the single highest-volume error on the site (1,382,569 occurrences across 76,882 users since 2025-11-25), and because each deploy ships a new bundle filename it was re-fingerprinted as a brand-new issue on every release, flooding error tracking and masking genuine regressions.

The fix follows the standard Gatsby/React pattern:

  • getInitialSiteSettings() now returns pure SSR defaults only, so the first client render is byte-identical to the server HTML and hydration is clean.
  • A new post-mount useEffect calls getStoredSiteSettings() to apply the user's persisted theme/skin/experience after the first paint.
  • static/scripts/theme-init.js already sets the body class and data-skin/data-wallpaper attributes before hydration, so the visual theme/skin is correct from the first paint — no flicker is introduced by deferring the React state.

This also resolves the same class of mismatch for users who saved website ("boring") mode or a non-default skin, since the first render now always matches the server.

Why: React #418 is recoverable (the page still works) but its volume was chronic and it drowned out real errors in error tracking. The root cause was contained to the settings initialization in App.tsx.

Verification note: This sandbox has no installed dependencies and a full Gatsby build requires 16GB plus the complete build pipeline, so a live browser hydration check wasn't possible here. The change is a render-parity fix established by construction — the initial client render now uses the exact same deterministic defaults as SSR. Please confirm on the Vercel preview (e.g. set a dark theme / non-default skin, reload, and verify no React #418 warning in the console).

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.

…initial render

App.tsx initialized siteSettings from window.__theme and localStorage during the
initial render. These don't exist during Gatsby SSR, so any user whose saved
theme/skin/wallpaper/experience differed from the defaults got a first client
render that disagreed with the server HTML, triggering a recoverable React #418
mismatch on nearly every page load.

Initialize siteSettings with pure SSR defaults (getInitialSiteSettings) so the
first client render is identical to the server, then load the persisted settings
in a post-mount effect (getStoredSiteSettings). theme-init.js already applies the
body class and data-skin/data-wallpaper attributes before hydration, so the visual
theme is correct from the first paint without flicker.

Generated-By: PostHog Code
Task-Id: 1acade7b-d5d6-4ab1-84da-b2d157a01b21
@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 03:42AM

@github-actions

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

6.30 MiB (+0.6 KiB / +0.0%)

Eager graph (static-import closure per entrypoint)

Entrypoint Eager size Budget Modules
✅ app 29.32 MiB (+20.1 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