Skip to main content
Frontend Developmentexistential-birds

remix-v2-perf-ssr-review

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.

Stars
60
Source
existential-birds/beagle
Updated
2026-05-31
Slug
existential-birds--beagle--remix-v2-perf-ssr-review
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/existential-birds/beagle/HEAD/plugins/beagle-react/skills/remix-v2-perf-ssr-review/SKILL.md -o .claude/skills/remix-v2-perf-ssr-review.md

Drops the SKILL.md into .claude/skills/remix-v2-perf-ssr-review.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Remix v2 Performance / SSR Code Review

Targets TypeScript route modules importing from @remix-run/*. See beagle-react: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
  • <PrefetchPageLinks> does not target routes whose loaders have side effects (analytics, mutations)
  • Every <Await> is wrapped in <Suspense> and has an errorElement
  • defer() is used only for genuinely slow data (>~50ms); fast data is awaited
  • Below-the-fold images use loading="lazy" and have width/height
  • Critical fonts/CSS are preloaded via the links export, not injected in body

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.

  6. Protocol — Pass: You completed the Pre-Report Verification Checklist in review-verification-protocol for this review.

When to Load References

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