rendering-hydration-suppress-warning — Claude Code rule: what it does
rendering-hydration-suppress-warning silences hydration warnings where the two renders are meant to differ: timestamps, per-render IDs, dates formatted for the visitor's locale.
MIT ★ 7,191 updated 2026-10-24
.claude/rules/rendering-hydration-suppress-warning.mdWhat rendering-hydration-suppress-warning does
Some values in an SSR app can't match between the two renders: an ID generated on each pass, a timestamp, a date formatted for the visitor's locale. The rule says to treat those as known differences and put suppressHydrationWarning on the element that holds the text.
The file is short markdown. It shows a Timestamp component that prints new Date().toLocaleString() and triggers the warning, then the same component with the attribute on span. No scripts, no config keys.
Hiding the warning doesn't reconcile the two renders. The rule tells you not to park genuine bugs behind the attribute and not to reach for it everywhere. If you can't explain why server and client disagree, suppressHydrationWarning only delays the investigation.
What it helps with
- Stop hydration noise from a timestamp that differs by design
- Keep genuine markup mismatches visible in the console
- Wrap a per-render ID so the warning goes away
- Defend in review why the attribute sits on this element
Example prompts for the agent
- Find the hydration mismatch in
Timestampcaused bynew Date()and wrap the output insuppressHydrationWarning. - Audit our
suppressHydrationWarningusages: which ones hide an actual bug rather than a locale difference? - Add the rule at
.claude/rules/rendering-hydration-suppress-warning.mdto this project.
How to install rendering-hydration-suppress-warning
Manually: put the files in place
.claude/rules/rendering-hydration-suppress-warning.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-suppress-warning.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/rendering-hydration-suppress-warning.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/rendering-hydration-suppress-warning.mdManually: put the files in place
.clinerules/rendering-hydration-suppress-warning.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-suppress-warning
How do I install rendering-hydration-suppress-warning in Claude Code?
Place the rule file in your project at .claude/rules/rendering-hydration-suppress-warning.md. That's the whole setup, since it's plain markdown.
What does rendering-hydration-suppress-warning do?
It explains which server/client differences are expected and shows how to wrap the differing text in an element carrying suppressHydrationWarning.
Should I add suppressHydrationWarning to every mismatch?
No. It's meant for values you know differ, such as dates or locale formatting. A real bug needs a fix, not a silenced warning.
Source text
rendering-hydration-suppress-warning.md · MIT
---
title: Suppress Expected Hydration Mismatches
impact: LOW-MEDIUM
impactDescription: avoids noisy hydration warnings for known differences
tags: rendering, hydration, ssr, nextjs
---
## Suppress Expected Hydration Mismatches
In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
**Incorrect (known mismatch warnings):**
```tsx
function Timestamp() {
return <span>{new Date().toLocaleString()}</span>
}
```
**Correct (suppress expected mismatch only):**
```tsx
function Timestamp() {
return (
<span suppressHydrationWarning>
{new Date().toLocaleString()}
</span>
)
}
```
© tech-leads-club · MIT · tech-leads-club/agent-skills