Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/rendering-hydration-no-flicker.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
server-dedup-props server-dedup-props — a rule for Claude Code about React Server Components: RSC-to-client serialization deduplicates by reference, not value. Server-side transforms like toSorted or filter create new references and double the payload. CX Codex +1 ★ 7,191repo stars rendering-usetransition-loading rendering-usetransition-loading — a rule that swaps hand-rolled loading flags in React components for useTransition. Useful when a spinner runs on its own useState. CX Codex +1 ★ 7,191repo stars server-cache-react server-cache-react instructs the assistant to deduplicate server-side operations with React.cache() and prevent cache misses from inline object arguments. CX Codex +1 ★ 7,191repo stars architecture-avoid-boolean-props The architecture-avoid-boolean-props rule keeps component variants out of boolean props and moves them into composition. Use it when conditional UI branches start spreading across a component. CX Codex +1 ★ 7,191repo stars bundle-barrel-imports The bundle-barrel-imports rule steers imports away from barrel files and toward source modules. It helps when a package exposes many re-exports and slows loading. CX Codex +1 ★ 7,191repo stars patterns-explicit-variants patterns-explicit-variants — a rule that pushes one component per mode instead of a single component buried under boolean props. The call site then says what renders. CX Codex +1 ★ 7,191repo stars async-suspense-boundaries async-suspense-boundaries guides Claude Code to place data fetching behind Suspense boundaries so headers, sidebars, and layout shells render without blocking. CX Codex +1 ★ 7,191repo stars architecture-compound-components The architecture-compound-components rule describes splitting complex UI components into pieces that share state through context. It fits components that have accumulated render props and conditional options. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open