Skip to content

Fix template theme hydration - #876

Draft
zahlekhan wants to merge 2 commits into
thesysdev:mainfrom
zahlekhan:codex/fix-template-theme-hydration
Draft

Fix template theme hydration#876
zahlekhan wants to merge 2 commits into
thesysdev:mainfrom
zahlekhan:codex/fix-template-theme-hydration

Conversation

@zahlekhan

Copy link
Copy Markdown
Contributor

Summary

  • use useSyncExternalStore with a deterministic server snapshot in the OpenUI Cloud template and example
  • add the same SSR-safe system-theme provider to the self-hosted CLI template
  • pass the resolved theme mode into the self-hosted AgentInterface
  • align the OSS openui-chat example with the template behavior

Root cause

The theme hook used a lazy useState initializer that returned light during server rendering but read prefers-color-scheme during the browser's first render. For users in dark mode, React hydrated light server markup with dark client properties, including a different logo URL, and reported an unrecoverable attribute mismatch.

useSyncExternalStore now supplies light as React's server and hydration snapshot, then switches to the live media-query snapshot after hydration and continues subscribing to system-theme changes.

Impact

Cloud and self-hosted apps generated by the CLI now hydrate deterministically while retaining responsive system light/dark mode behavior. The checked-in Cloud and OSS examples use the same implementation.

Validation

  • Cloud template: npm test (3 passed)
  • Cloud template: npm run typecheck
  • Cloud template: npm run lint (passes with one pre-existing no-img-element warning)
  • Cloud template: npm run build
  • Cloud template: dark-mode browser smoke test with no hydration errors
  • Self-hosted template: npm run lint
  • Self-hosted template: npx tsc --noEmit
  • Self-hosted template: OPENAI_API_KEY=build-validation-placeholder npm run build

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant