rendering-hydration-no-flicker — Claude Code rule
rendering-hydration-no-flicker prevents server render failures and interface flickering when displaying content tied to browser storage.
MIT ★ 7,191 updated 2026-10-24
.claude/rules/rendering-hydration-no-flicker.mdWhat rendering-hydration-no-flicker does
Calling localStorage during server execution breaks the build because the storage API is undefined outside the browser. Deferring reads into a useEffect hook avoids the runtime exception, but it introduces an unwelcome visual flash when the default state flips after hydration.
This rule instructs the assistant to inject an inline <script> block with an immediately invoked function. The browser executes this script synchronously right before painting the target element, applying the stored attributes directly to the DOM.
Without an inline script updating the element ahead of time, client-only preferences will flicker against server-generated defaults on every page load.
What it helps with
- stop server rendering crashes caused by missing window storage objects
- eliminate the visible flash when switching from default themes to saved preferences
- insert synchronous inline scripts to modify DOM nodes before hydration begins
- keep server output aligned with stored client configuration
Example prompts for the agent
- Refactor the theme provider so it applies saved settings without initial page flash.
- Resolve hydration markup differences when reading browser preferences.
- Add an inline script to assign the wrapper class before client hydration runs.
How to install rendering-hydration-no-flicker
Manually: put the files in place
.claude/rules/rendering-hydration-no-flicker.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/rendering-hydration-no-flicker.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/rendering-hydration-no-flicker.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/rendering-hydration-no-flicker.mdManually: put the files in place
.clinerules/rendering-hydration-no-flicker.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about rendering-hydration-no-flicker
How to install rendering-hydration-no-flicker in Claude Code?
Place the rule file at .claude/rules/rendering-hydration-no-flicker.md inside your project directory.
What does rendering-hydration-no-flicker do?
It guides the agent to handle client storage via synchronous inline scripts, avoiding SSR breakage and hydration flickers.
Why is useEffect discouraged for initial theme display?
The hook runs after hydration completes, forcing the UI to paint fallback values first and causing a noticeable flash.
Source text
rendering-hydration-no-flicker.md · MIT
---
title: Prevent Hydration Mismatch Without Flickering
impact: MEDIUM
impactDescription: avoids visual flicker and hydration errors
tags: rendering, ssr, hydration, localStorage, flicker
---
## Prevent Hydration Mismatch Without Flickering
When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
**Incorrect (breaks SSR):**
```tsx
function ThemeWrapper({ children }: { children: ReactNode }) {
// localStorage is not available on server - throws error
const theme = localStorage.getItem('theme') || 'light'
return (
<div className={theme}>
{children}
</div>
)
}
```
Server-side rendering will fail because `localStorage` is undefined.
**Incorrect (visual flickering):**
```tsx
function ThemeWrapper({ children }: { children: ReactNode }) {
const [theme, setTheme] = useState('light')
useEffect(() => {
// Runs after hydration - causes visible flash
const stored = localStorage.getItem('theme')
if (stored) {
setTheme(stored)
}
}, [])
return (
<div className={theme}>
{children}
</div>
)
}
```
Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
**Correct (no flicker, no hydration mismatch):**
```tsx
function ThemeWrapper({ children }: { children: ReactNode }) {
return (
<>
<div id="theme-wrapper">
{children}
</div>
<script
dangerouslySetInnerHTML={{
__html: `
(function() {
try {
var theme = localStorage.getItem('theme') || 'light';
var el = document.getElementById('theme-wrapper');
if (el) el.className = theme;
} catch (e) {}
})();
`,
}}
/>
</>
)
}
```
The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
© tech-leads-club · MIT · tech-leads-club/agent-skills