remix-v2-perf-ssr-review

name	remix-v2-perf-ssr-review
description	Reviews Remix v2 code for caching header misuse, missing server/client split, hydration mismatches (Date, Math.random, locale), prefetch hygiene, and asset bottlenecks. Use when reviewing routes that export headers, use .server.ts/.client.ts, or render dates/IDs in a Remix v2 codebase.

Remix v2 Performance / SSR Code Review

Targets TypeScript route modules importing from @remix-run/*. See remix-v2-perf-ssr for canonical patterns.

Quick Reference

Issue Type	Reference
Missing headers export, unsafe public cache, child-drops-parent headers, missing Vary: Cookie, Set-Cookie + public	references/caching-headers.md
Server libs imported without .server.ts, process.env.SECRET_* leaks, typeof window substituted for .server.ts	references/server-client-split.md
new Date() in render, Math.random() in keys, locale formatting without explicit locale, missing useId(), blanket suppressHydrationWarning	references/hydration.md
prefetch="render" on every link, defer for fast data, missing <Suspense> around <Await>, prefetch to side-effect routes	references/prefetch-streaming.md
dangerouslySetInnerHTML with untrusted data, missing loading="lazy", missing links preload, stylesheet injected in body	references/assets.md

Review Checklist

• Routes serving data export headers (even if the answer is no-store)
• Child routes serving personalized data export their own headers (otherwise they silently inherit the parent's policy)
• Cache-Control: public is never set on auth'd or cookie-bearing responses
• Vary: Cookie is set when cache decision depends on session
• Server-only libs (prisma, bcrypt, node:fs, jsonwebtoken) live in *.server.ts or app/.server/
• Secret env (process.env.STRIPE_SECRET_KEY, etc.) is read only inside loaders/actions or .server modules
• Client-exposed env is whitelisted into window.ENV, never raw process.env
• typeof window === "undefined" is not used as a substitute for .server.ts (treeshaking is unreliable)
• No new Date(), Math.random(), Date.now(), crypto.randomUUID() in JSX render path
• Locale formatting (toLocaleDateString, Intl.DateTimeFormat) passes an explicit locale
• Components generating IDs use useId(), not Math.random() or counters
• suppressHydrationWarning is scoped to a single element with a code comment explaining why
• <Link prefetch="render"> is reserved for above-the-fold critical nav, not lists
• does not target routes whose loaders have side effects (analytics, mutations)

Valid Patterns (Do NOT Flag)

These are correct Remix v2 usage and must not be reported as issues:

• Route without headers export when caching is intentionally off — auth'd dashboards, account pages, and routes wrapped in a layout that already returns no-store may legitimately omit headers. Flag only if the route serves cacheable public content with no headers.
• new Date() inside useEffect — runs after hydration on the client only; no SSR mismatch possible. Same for Date.now(), Math.random(), crypto.randomUUID() inside effects.
• Math.random() / new Date() inside event handlers — handlers run after hydration. Only flag when the value is used during render.
• suppressHydrationWarning on a single <time> (or similar) element with a clear comment — accepted narrow escape for known-divergent values like absolute timestamps formatted client-side. Flag only when applied at a parent that wraps a large subtree or with no explanation.
• .client.ts files for client-only libraries — Stripe.js, map widgets, chart libs that read window belong in *.client.ts by convention; do not flag the file extension.
• useId() with extra characters appended — `${id}-input` is the documented pattern for multi-element components; do not flag as "non-stable id."
• Raw ISO string rendered in SSR + reformatted in useEffect — the canonical hydration-safe time pattern; flag only if the reformat happens in render.
• headers export returning {} or no-store — explicit "do not cache" is a deliberate decision and should not be flagged as misuse.
• <Link prefetch="intent"> on standard nav — the recommended default; flag only when the loader has side effects.
• loaderHeaders forwarded to the document via headers export — co-locating data and document policy is the documented pattern, not duplication.

Context-Sensitive Rules

Apply these only when the specific context applies:

Issue	Flag ONLY IF
Missing headers export	Route serves cacheable public content (not auth'd, not personalized, not intentionally no-store)
Child route missing headers	An ancestor exports headers AND its policy is broader than the child's cacheability (e.g., parent caches public + s-maxage, child serves personalized data)
Cache-Control: public	Loader actually reads session / user state (or response carries Set-Cookie)
Vary: Cookie missing	Loader branches response shape on a cookie (theme, locale, session) AND the cache is public/s-maxage
new Date() / Math.random() / Date.now()	Call site is in render path — NOT in useEffect, event handler, <ClientOnly>, or post-hydration code
Locale formatting without locale	Result is rendered into JSX (not used only inside an effect / handler)
<Link prefetch="render">	Link is inside a list / .map() iterator (not above-the-fold critical nav)
<Link prefetch="intent"> to side-effect loader	Loader has observable side effects (analytics write, counter increment, log emit) AND doesn't branch on the Purpose: prefetch header
Server lib import without .server.ts	Importing file is reachable from the client graph (route module, non-.server util reached from a component)
process.env.SECRET_* reference	Reference is in a component body or in a non-.server module reached from the client graph
Missing loading="lazy" on image	Image is rendered below the fold (not in <header>, hero section, or above any <main> content)
Missing width/height on image	Project does NOT use a build-time image processor that injects dimensions

Hard gates (before writing findings)

Run these in order. Do not draft user-facing findings until every gate passes for the batch you are about to report.

1. Location evidence — Pass: Each issue lists the repo path and either a line range or a short verbatim quote from the file you read (not memory or diff-only guesswork). Cache, hydration, and .server claims without a concrete file path are not reportable.

2. Exemption check — Pass: For each issue, you can state in one line why it is not covered by Valid Patterns (Do NOT Flag). In particular: confirm a missing headers export is not on an intentionally-uncacheable route, confirm .client.ts is not a legitimate client-only library, confirm suppressHydrationWarning is not scoped + commented.

3. Hydration-context check — Pass: Before flagging new Date(), Math.random(), Date.now(), crypto.randomUUID(), or locale formatting, confirm the call site is in the render path of a component. Calls inside useEffect, useLayoutEffect, event handlers, callbacks passed to setTimeout/requestAnimationFrame, or inside <ClientOnly>{() => ...}</ClientOnly> are post-hydration and must not be flagged.

4. Parent/child headers chain check — Pass: Before flagging "missing headers on a child" as silent cache inheritance, confirm an ancestor route in the matched chain actually exports headers (search the route file tree for export const headers or export function headers) AND that the inherited policy is wider than the child's cacheability profile. If no ancestor exports headers, the issue is just "no caching configured," not "child silently inherits parent's cache."

5. Server/client boundary check — Pass: Before flagging a server-lib import as a leak, confirm the importing file is reachable from the client graph — i.e., it's a route module, a non-.server utility transitively imported by a route's default export, or a .client.ts file. Imports inside loader, action, headers, or other .server.ts modules are not leaks.

When to Load References

• Reviewing route headers exports, Cache-Control strings, CDN policy → references/caching-headers.md
• Reviewing .server.ts / .client.ts files, imports of prisma/bcrypt/fs, or process.env access → references/server-client-split.md
• Reviewing any component that renders dates, IDs, locale-formatted values, or browser globals → references/hydration.md
• Reviewing <Link prefetch>, <PrefetchPageLinks>, defer, <Await>, <Suspense>, or <RemixServer abortDelay> → references/prefetch-streaming.md
• Reviewing <img>, <link>, dangerouslySetInnerHTML, font/CSS loading, or links export → references/assets.md

Review Questions

1. Does every route that serves cacheable data declare a Cache-Control policy, even if "no cache"?
2. Are personalized routes free of public caching, with Vary: Cookie where session influences the response?
3. Do server libs (prisma, bcrypt, fs, secret env access) live in *.server.ts modules that the build will reject if leaked?
4. Are public env vars whitelisted into window.ENV rather than spread from process.env?
5. Are new Date() / Math.random() / locale formatting calls limited to effects, handlers, or <ClientOnly> — not render?
6. Do components needing IDs use useId()?
7. Are <Link prefetch> modes matched to context (render only above the fold, intent for nav, viewport/intent in lists)?
8. Is defer() used only for genuinely slow data, with <Await> always paired with <Suspense> AND errorElement?
9. Are images sized, lazy-loaded below the fold, and critical fonts/CSS preloaded via the links export?
10. Is dangerouslySetInnerHTML used only with sanitized HTML or safely serialized JS?

Before Submitting Findings

Complete Hard gates (especially gate 3 — hydration-context check, and gate 5 — server/client boundary check), then report only issues that still pass the review-verification-protocol pre-report checks. Finding format: [FILE:LINE] ISSUE_TITLE with a verbatim quote of the offending code and a one-line rationale tied to the specific Remix v2 contract being violated.

Additional Documentation

• Reviewing headers exports, CDN cache policy, Vary, parent/child merge, Set-Cookie interactions → references/caching-headers.md
• Reviewing .server.ts / .client.ts boundaries, process.env access, window.ENV pattern → references/server-client-split.md
• Reviewing render-time Date/Math.random/locale issues, useId, suppressHydrationWarning scope → references/hydration.md
• Reviewing <Link prefetch> modes, <PrefetchPageLinks> targets, defer/<Await>/<Suspense> structure → references/prefetch-streaming.md
• Reviewing dangerouslySetInnerHTML, image loading/width/height, font/CSS preload, stylesheet placement → references/assets.md
• Canonical patterns and decision gates → remix-v2-perf-ssr