Cursor rule

1---
2alwaysApply: false
3---
4 
5## Prevent Hydration Mismatch Without Flickering
6 
7When 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.
8 
9**Incorrect (breaks SSR):**
10 
11```tsx
12function ThemeWrapper({ children }: { children: ReactNode }) {
13  // localStorage is not available on server - throws error
14  const theme = localStorage.getItem('theme') || 'light'
15  
16  return (
17    <div className={theme}>
18      {children}
19    </div>
20  )
21}
22```
23 
24Server-side rendering will fail because `localStorage` is undefined.
25 
26**Incorrect (visual flickering):**
27 
28```tsx
29function ThemeWrapper({ children }: { children: ReactNode }) {
30  const [theme, setTheme] = useState('light')
31  
32  useEffect(() => {
33    // Runs after hydration - causes visible flash
34    const stored = localStorage.getItem('theme')
35    if (stored) {
36      setTheme(stored)
37    }
38  }, [])
39  
40  return (
41    <div className={theme}>
42      {children}
43    </div>
44  )
45}
46```
47 
48Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
49 
50**Correct (no flicker, no hydration mismatch):**
51 
52```tsx
53function ThemeWrapper({ children }: { children: ReactNode }) {
54  return (
55    <>
56      <div id="theme-wrapper">
57        {children}
58      </div>
59      <script
60        dangerouslySetInnerHTML={{
61          __html: `
62            (function() {
63              try {
64                var theme = localStorage.getItem('theme') || 'light';
65                var el = document.getElementById('theme-wrapper');
66                if (el) el.className = theme;
67              } catch (e) {}
68            })();
69          `,
70        }}
71      />
72    </>
73  )
74}
75```
76 
77The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
78 
79This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
80