LLM Best Practices

Hydration

Last updated 2 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Hydration is the client step that makes server-rendered HTML interactive: the framework re-runs the component tree in the browser, checks it against the existing DOM, reuses the nodes, and attaches handlers. A page that looks ready but ignores clicks on slow phones is waiting on hydration. Ship less client JavaScript or hydrate only interactive parts. A page with no interactivity needs no hydration and no JavaScript.

Rules

  • Shrink the work: Astro islands (client:* directives) hydrate only interactive components; server-component output never hydrates, only Client Components do; Suspense boundaries hydrate independently (suspense-boundary); Qwik skips hydration by resuming server state on first interaction (resumability).
  • Make the first client render match the server HTML. Mismatches come from window or localStorage checks during render, Date.now(), Math.random(), locale or timezone differences, client-only auth state, invalid HTML nesting, and browser extensions that alter the DOM.
  • React may recover by client-rendering the affected part, but it does not guarantee attribute differences are patched and handlers can attach to the wrong elements. Treat every mismatch as a bug.
  • Read browser-only values in useEffect after mount (a second render), use useId for IDs, and use suppressHydrationWarning only for unavoidable text such as timestamps (one level deep).
function Clock() {
  const [time, setTime] = useState("");           // same on server and first client render
  useEffect(() => setTime(new Date().toLocaleTimeString()), []);
  return <time>{time}</time>;
}

Backlinks