Skip to main content
rule CX Codex

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

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

What 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 Timestamp caused by new Date() and wrap the output in suppressHydrationWarning.
  • Audit our suppressHydrationWarning usages: which ones hide an actual bug rather than a locale difference?
  • Add the rule at .claude/rules/rendering-hydration-suppress-warning.md to this project.

How to install rendering-hydration-suppress-warning

Manually: put the files in place

.claude/rules/rendering-hydration-suppress-warning.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-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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
decomposition-planning-roadmap decomposition-planning-roadmap is a Claude Code skill that maps out monolith decomposition and migration. It activates for service extraction planning, work prioritization, and progress tracking. CX Codex +1 322installs seo Walks Claude through technical and on-page SEO: crawl rules, canonicals, sitemaps, meta tags, JSON-LD. Useful when pages don't get indexed or snippets look broken. CX Codex +1 ★ 7,191repo stars best-practices best-practices is a Claude Code skill for checking web code security, browser compatibility, and code quality. It runs on requests for a security review or code modernization. CX Codex +1 ★ 7,191repo stars js-index-maps The js-index-maps rule replaces repeated .find() calls on one key with a Map index. Use it when array lookups happen many times. CX Codex +1 ★ 7,191repo stars bundle-defer-third-party bundle-defer-third-party prevents third-party trackers from inflating the initial bundle. It instructs the assistant to load analytics and monitoring after hydration. CX Codex +1 ★ 7,191repo stars bundle-conditional The bundle-conditional rule recommends loading large modules only when their feature is activated. It applies to lazy-loaded data and browser-only code in SSR builds. CX Codex +1 ★ 7,191repo stars react19-no-forwardref react19-no-forwardref is a Claude Code rule covering React 19 ref and context changes: pass ref as a prop and use use() instead of useContext(). It supports React 19 migrations. CX Codex +1 ★ 7,191repo stars advanced-init-once advanced-init-once prevents running app-wide startup logic inside component useEffect([]) hooks and suggests module-level guards or top-level initialization instead. CX Codex +1 ★ 7,191repo stars

More in the catalog

Project sponsors

Companies that keep this analytics open