solidstart-hydration-guard

name	solidstart-hydration-guard
description	SolidStart hydration guard: keep SSR/CSR output identical, gate browser-only APIs, use stable IDs, align Suspense/resource fallbacks, and use clientOnly/onMount for client-only UI.
metadata	{"globs":["src/app.tsx","src/routes/**/*","src/entry-*.tsx"]}

SolidStart Hydration Guard

SSR/CSR Symmetry

• No browser-only globals during SSR: guard window, document, localStorage, matchMedia, ResizeObserver with if (!isServer) or typeof window !== "undefined".
• Keep server HTML stable: avoid Math.random(), Date.now() in render; use createUniqueId() or values passed from server data.
• Ensure Suspense fallbacks are the same server/client; don’t branch on browser checks for fallback.
• Avoid rendering different markup based on isServer unless the client version is wrapped in clientOnly or <NoHydration>.

Stable IDs & Data

• For IDs, use createUniqueId() inside components, or pass stable IDs from server data/props.
• Call createUniqueId() the same number of times on server and client; don’t gate it behind isServer or <NoHydration>.
• Only pass JSON-serializable data from server fetchers; avoid class instances/functions.

Resources & Suspense

• For createResource/router createAsync, keep initialValue consistent between server and client.
• Prefer ssrLoadFrom: "server" when you need the server-rendered HTML to match hydration; "initial" will re-fetch on the client.
• Use onHydrated to inspect resource values during hydration when debugging.
• Resources inside non-hydrating sections are not serialized; wrap client-needed data in <Hydration> or pass it through props.
• Use deferStream only when you can set headers/status before flush; otherwise keep data in initial render to avoid mismatch.

Client-Only UI

• Wrap client-only components with clientOnly and provide a SSR-safe fallback.
• For browser-only effects (e.g., viewport size), run inside onMount or createEffect gated by !isServer.
• Effects do not run during the initial client hydration, so they cannot fix initial mismatches.
• <Portal> is client-only with hydration disabled; use it for overlays that should not hydrate.
• <NoHydration> skips hydration for its subtree; use <Hydration> to resume for interactive islands when needed.

Streaming & Headers

• When streaming (renderToStream), set HttpHeader/HttpStatusCode before first flush; hydrate assumes status/headers are fixed.

Router Integration

• Wrap <FileRoutes /> with <Suspense> in the Router root to avoid hydration errors.
• Keep route preload functions pure; SSR runs them and resumes on the client during hydration.

Document & Script Setup

• Include <HydrationScript /> once (SolidStart injects it via the document assets slot).

Debug Checklist

• Verify Router root uses <Suspense> and that fallbacks match server/client.
• Check for non-deterministic render output (Math.random(), Date.now()).
• Confirm createUniqueId() call counts are identical on server/client.
• Validate query args and server data are JSON-serializable.
• If you must render different client UI, isolate it with clientOnly, <NoHydration>, or <Portal>.

Quick Checks

• Are all browser APIs guarded?
• Are IDs and fallbacks stable between server and client?
• Are Suspense boundaries identical on both sides?