Remix v2 Data Flow Code Review

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

Scope

• In scope: route modules under app/routes/ exporting loader, action, shouldRevalidate, or headers; components that consume useLoaderData, useActionData, useNavigation, useFetcher, useRevalidator, .
• Out of scope: form ergonomics (
  markup, accessibility, useFetcher UI patterns) → covered by remix-v2-forms-review. Route module conventions, file naming, nested routing, error boundary placement → covered by remix-v2-routing-review.
• Imports expected: @remix-run/node (or @remix-run/cloudflare / @remix-run/deno) for server utilities; @remix-run/react for hooks and components.

Quick Reference

Review Checklist

• [ ] Data needed for first render is in loader, not useEffect
• [ ] Loaders only read; writes live in action
• [ ] request.formData() results are validated (zod/valibot/invariant) before use
• [ ] Loader/action return values are projected DTOs — no password hashes, tokens, or internal_* fields
• [ ] useLoaderData() uses the type annotation form (not as Foo)
• [ ] 404 / auth short-circuits throw a Response (or json/redirect), never a plain Error or string
• [ ] Successful action returns redirect(...) (PRG); validation failures return json({ errors }, { status: 400 })
• [ ] Action handles both success and error branches; no silent return null
• [ ] params.foo is checked with invariant / zod before use
• [ ] Pending UI reads useNavigation() / fetcher.state — no useTransition
• [ ] formMethod comparisons use UPPERCASE ("POST", not "post")
• [ ] shouldRevalidate returns defaultShouldRevalidate by default; opt-outs are narrow and justified
• [ ] defer() is used only when at least one promise streams (no await before passing it)
• [ ] Every is wrapped in and has an errorElement
• [ ] useRevalidator().revalidate() is reserved for focus/polling/SSE — not called immediately after a post or fetcher.submit (Remix already revalidates).

Valid Patterns (Do NOT Flag)

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

• useEffect for client-only data — Loaders run server-side; localStorage, window dimensions, IntersectionObserver, and browser-only APIs belong in useEffect.
• loader returning null — A loader may legitimately return null (e.g. optional resource not present); flag only if it should be a 404 throw.
• useLoaderData() as type annotation — The is a generic parameter feeding SerializeFrom, not a as-style type assertion. Do not flag it as "unsafe cast."
• Bare new Response(body, init) returns — v2 routes may return any Response; json() is an ergonomic wrapper, not a requirement. Non-JSON bodies (binary, text, streams) correctly skip json().
• return redirect(...) from an action — Both return redirect(...) and throw redirect(...) are legal in actions; throwing is required only from non-action helpers when you want to exit the calling function.
• loader declared without the request arg — Loaders may destructure only what they need ({ params }, { context }, or () with no args); the unused arg is not a bug.
• Parent loader revalidated after an unrelated action — This is default Remix behavior, not a smell. Flag only if shouldRevalidate exists and is wrong.
• Action returning json({ errors }, { status: 400 }) — This is the canonical validation-error pattern (keeps the form route rendered with field errors). Not the same as the "no redirect on success" anti-pattern.
• useRevalidator for focus / polling / cross-tab sync — These are the documented use cases; only flag manual revalidate() calls that immediately follow a post or fetcher.submit Remix would already revalidate.
• SerializeFrom-induced type changes — Date typed as string, Map typed as {} after deserialization is correct wire-format behavior, not a typing bug.

Context-Sensitive Rules

Only flag these issues when the specific context applies:

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 to the route module and either a line range or a short verbatim quote from the file you read (not from memory or diff-only guesswork). Loader/action issues without a path to the export async function loader|action are not reportable.

1. 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 useEffect is not loading client-only data; confirm a bare Response return is not intentionally non-JSON; confirm a loader returning null is not a legitimate optional read.

1. Type-annotation vs type-assertion check — Pass: Before flagging an "unsafe cast" on loader/action consumption, confirm the code uses as (assertion) — not useLoaderData() (annotation) and not useActionData() (annotation). The generic form is the documented safe path and must not be flagged.

1. v1 holdover check — Pass: Before flagging "missing pending state," grep the file for useTransition, transition.submission, fetcher.type, formMethod === "post" or formMethod==='post' (lowercase, any whitespace/quote variation), and LoaderArgs / ActionArgs. If present, the finding is a v1-holdover migration issue, not a missing-feature issue — label it accordingly.

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

When to Load References

• Reviewing a loader body, return shape, params, throws, or sensitive-field leaks → references/loaders.md
• Reviewing an action body, FormData validation, success/error branches, or PRG redirect → references/actions.md
• Reviewing useNavigation / useTransition migrations, shouldRevalidate, or useRevalidator use → references/revalidation.md
• Reviewing defer(), , , or streaming decisions → references/defer-await.md

Review Questions

1. Is data needed for first render fetched in a loader, or is it stuck in a useEffect that defeats SSR and revalidation?
2. Does every loader return a projected DTO, or do raw ORM records (with password, token, internal_* fields) leak to the browser?
3. Does every action validate request.formData() with a schema before touching the database?
4. Does the success branch of each action redirect(...) so refresh / back behaves correctly (PRG)?
5. Is the consumer code using useLoaderData() (annotation) — not useLoaderData() as Foo (assertion)?
6. Do any v1 holdovers remain (useTransition, transition.submission, fetcher.type, lowercase formMethod, LoaderArgs / ActionArgs)?
7. Does shouldRevalidate return a literal false, or does it reach for defaultShouldRevalidate and opt out narrowly?
8. Is defer() used only when at least one promise is passed unresolved, and is every wrapped in with an errorElement?

Additional Documentation

• Canonical Remix v2 data-flow patterns and v1 → v2 diff → remix-v2-data-flow
• Pre-report verification checklist → review-verification-protocol

Before Submitting Findings

Complete Hard gates (especially gate 5), then report only issues that still pass the review-verification-protocol pre-report checks.