Remix v2 Data Flow

intent

Remix v2 ships data to the browser through loaders (server-side reads) and actions (server-side mutations). Use this skill when writing route module exports (loader, action), reading that data in components (useLoaderData, useActionData), streaming responses with defer(), or managing revalidation and pending UI. Know this when you're building SSR-first routes, need to decide between a loader and a useEffect, want to throw a redirect for auth guards, or are converting from v1's useTransition to v2's useNavigation.

inputs

Remix v2 runtime environment

• Node.js, Cloudflare Workers, or Deno target (adapters available via @remix-run/cloudflare, @remix-run/deno).
• Route module with optional loader and/or action exports.

External dependencies

• @remix-run/node (or target adapter) for server utilities: json(), redirect(), defer(), type definitions.
• @remix-run/react for client hooks: useLoaderData(), useActionData(), useFetcher(), useNavigation(), useAsyncError(), <Form>, <Await>, <Suspense>.
• Database client (Prisma, Drizzle, raw SQL, etc.) if fetching persistent state.
• Form parsing library (Zod, Valibot, etc.) if validating FormData in actions.
• Optional: shouldRevalidate function if you need fine-grained revalidation control.

Context and params available in loaders/actions

• request: Request , the HTTP request object (method, headers, URL, body).
• params: Record<string, string> , route dynamic segments (e.g. params.projectId from /projects/:projectId).
• context: Record<string, unknown> , app-level context passed at server init (DB instances, config, etc.).

Edge cases and operational constraints

• Loaders and actions are server-only. Code inside them does not ship to the browser.
• The return value of a loader is serialized to JSON and sent to the client. Never return full database objects, password hashes, API keys, or internal flags.
• Loaders run on every GET navigation, prefetch, and automatic revalidation. Mutations must live in actions, not loaders.
• All loaders on a page revalidate automatically after an action succeeds, even if their params didn't change. Use shouldRevalidate to skip expensive parents.
• Network timeout, JSON parse errors, or database connection failures in a loader bubble to the route's ErrorBoundary.
• Streaming responses via defer() require <Suspense> + <Await> on the client. Unhandled promise rejections in deferred data tear down the entire page unless caught by an errorElement in the <Await>.

procedure

Step 1: Export a loader for server-side reads (SSR + client navigations)

Input: Route module context, LoaderFunctionArgs with request, params, context.

Output: A Response object (typically via json(data, init)).

Declare an async function named loader in your route module. Fetch or compute all data needed for correct first render. Call json(data) to wrap your object and set application/json content-type with a 200 status. If you need a non-200 status (e.g. 404) or custom headers, pass an init object as the second argument.

import { json, type LoaderFunctionArgs } from "@remix-run/node";

export async function loader({ request, params, context }: LoaderFunctionArgs) {
  const { projectId } = params;
  const project = await db.project.findUnique({ where: { id: projectId } });
  if (!project) {
    throw json({ message: "Project not found" }, { status: 404 });
  }
  return json({ project: { id: project.id, name: project.name } });
}

Type annotation: Use type LoaderFunctionArgs from @remix-run/node to type-check your parameters.

---

Step 2: Read loader data in a component with useLoaderData<typeof loader>()

Input: The exported loader function.

Output: Typed data object in the component.

Inside the route's default export component, call useLoaderData with the loader as a generic parameter. Pass typeof loader (not an assertion, but a type annotation) so TypeScript infers the shape and applies SerializeFrom<typeof loader> (the wire-format transformation: Date becomes string, class methods vanish, undefined fields are stripped).

import { useLoaderData } from "@remix-run/react";

export default function Project() {
  const { project } = useLoaderData<typeof loader>();
  // typeof project.name is string (JSON serialized)
  return <h1>{project.name}</h1>;
}

Serialization reality check: If your loader returns { createdAt: new Date() }, the wire value is a string ISO timestamp. Calling .getFullYear() on it will crash at runtime. The type annotation already says string, so the type-check catches this.

---

Step 3: Export an action to handle mutations (POST/PUT/PATCH/DELETE)

Input: Route module context, ActionFunctionArgs with request, params, context.

Output: A Response (redirect on success, or json(errors) on validation failure).

Declare an async function named action in the same route module. Check the request.method if the route handles multiple methods. Parse the request body with await request.formData() (for form submissions) or await request.json() (for JSON payloads). Validate the data with Zod or similar. If validation fails, return json({ errors }, { status: 400 }). If success, mutate the database and return redirect(url) to a new page, or return json(data) if the user stays on the same route.

import { json, redirect, type ActionFunctionArgs } from "@remix-run/node";
import { NewProjectSchema } from "~/schemas";

export async function action({ request }: ActionFunctionArgs) {
  if (request.method !== "POST") {
    throw json({ message: "Method not allowed" }, { status: 405 });
  }
  const form = await request.formData();
  const parsed = NewProjectSchema.safeParse(Object.fromEntries(form));
  if (!parsed.success) {
    return json(
      { errors: parsed.error.flatten().fieldErrors },
      { status: 400 }
    );
  }
  const project = await db.project.create({ data: parsed.data });
  return redirect(`/projects/${project.id}`);
}

---

Step 4: Submit mutations via <Form method="post"> to trigger the action and revalidate loaders

Input: JSX component, form fields.

Output: Route action executed, loaders revalidated, UI updated.

In your component, render a <Form> from @remix-run/react with method="post" (or "put", "patch", "delete"). Remix intercepts the submission, runs the action on the server, and then automatically revalidates all matching loaders. The page stays in sync with the server without manual refetch logic.

import { Form, useActionData } from "@remix-run/react";

export default function NewProject() {
  const actionData = useActionData<typeof action>();
  return (
    <Form method="post">
      <input name="name" required />
      {actionData?.errors?.name && <p>{actionData.errors.name}</p>}
      <button type="submit">Create</button>
    </Form>
  );
}

---

Step 5: Use useFetcher for mutations that don't change the URL or history

Input: Component context, fetcher callback.

Output: Mutation without navigation, inline pending state.

For inline edits, list toggles, or popover forms that don't warrant a URL change, call useFetcher() from @remix-run/react. Use fetcher.Form, fetcher.submit(), or fetcher.load() to invoke a separate route's action without navigating. The current route stays put, and only the fetcher's state updates.

import { useFetcher } from "@remix-run/react";

export default function ProjectRow({ project }) {
  const fetcher = useFetcher();
  return (
    <div>
      <p>{project.name}</p>
      <fetcher.Form method="post" action={`/projects/${project.id}/toggle-archived`}>
        <button type="submit">
          {fetcher.state === "submitting" ? "Saving..." : "Archive"}
        </button>
      </fetcher.Form>
    </div>
  );
}

---

Step 6: Stream slow data with defer() and <Suspense> + <Await>

Input: Loader returning both critical and deferred (non-awaited) promises.

Output: HTML streamed to browser, slow queries resolve in the background.

In a loader, separate fast data from slow data. Await the critical fields, but pass slow promises unawaited into defer(). On the client, wrap the slow data in <Suspense> + <Await> to render a fallback while the promise resolves.

// Server: loader
export async function loader() {
  const reviews = db.review.findMany(); // Don't await ,  this is slow.
  const product = await db.product.findUnique({ where: { id: 1 } }); // Critical, await.
  return defer({ product, reviews });
}

// Client: component
import { Suspense } from "react";
import { Await } from "@remix-run/react";

export default function Product() {
  const { product, reviews } = useLoaderData<typeof loader>();
  return (
    <div>
      <h1>{product.name}</h1>
      <Suspense fallback={<div>Loading reviews...</div>}>
        <Await resolve={reviews}>
          {(r) => <ReviewList reviews={r} />}
        </Await>
      </Suspense>
    </div>
  );
}

---

Step 7: Handle deferred promise rejections with errorElement + useAsyncError()

Input: <Await> component with rejected promise, error boundary component.

Output: Inline error UI without tearing down the page.

When a deferred promise rejects, an <Await errorElement={...}> catches it and renders the error component locally. Inside that component, call useAsyncError() to access the rejection value. This keeps the page interactive while a single slow data stream fails.

function ReviewsError() {
  const error = useAsyncError();
  return <p>Failed to load reviews: {String(error)}</p>;
}

<Suspense fallback={<div>Loading reviews...</div>}>
  <Await resolve={reviews} errorElement={<ReviewsError />}>
    {(r) => <ReviewList reviews={r} />}
  </Await>
</Suspense>

---

Step 8: Throw a Response from a loader or action for early exits (auth, 404, redirects)

Input: Loader or action function, guard condition.

Output: HTTP response sent to client (redirect, 404, 403, etc.).

To short-circuit a loader or action (e.g. user not authenticated), throw a Response object. Throwing a plain Error will not be caught by useRouteError() / isRouteErrorResponse(). Use throw redirect() for auth guards and throw json(message, { status: 404 }) for missing resources.

export async function loader({ request, context }: LoaderFunctionArgs) {
  const user = context.user;
  if (!user) {
    throw redirect("/login");
  }
  const data = await db.secrets.findMany();
  return json({ data });
}

---

Step 9: Use useNavigation() to display pending UI during navigation and form submission

Input: Component context.

Output: Pending state flags and form data.

Call useNavigation() from @remix-run/react to read the current navigation state (idle, loading, submitting) and inspect formData, formMethod (uppercase: "POST", "GET", etc.), and location. Branch on state to show spinners or disable buttons during submission.

import { useNavigation } from "@remix-run/react";

export default function ProjectForm() {
  const navigation = useNavigation();
  const isSubmitting = navigation.state === "submitting";
  return (
    <Form method="post">
      <input name="name" disabled={isSubmitting} />
      <button disabled={isSubmitting}>
        {isSubmitting ? "Saving..." : "Save"}
      </button>
    </Form>
  );
}

Note on GET vs POST state: POST submissions go idle -> submitting -> loading -> idle. GET submissions go idle -> loading -> idle. Use navigation.formData presence to detect GET form submissions, not state === "submitting".

---

Step 10: Use shouldRevalidate to skip expensive loaders after actions

Input: Route module, ShouldRevalidateFunctionArgs.

Output: Boolean controlling whether a specific loader reruns.

By default, all loaders on a page revalidate after an action succeeds. Export a shouldRevalidate function to opt out of revalidation for specific routes (e.g. a heavy sidebar loader that didn't change). Return false to skip the loader; return true to revalidate.

import { type ShouldRevalidateFunctionArgs } from "@remix-run/react";

export function shouldRevalidate({ actionResult, defaultShouldRevalidate }: ShouldRevalidateFunctionArgs) {
  // Skip revalidation if the action didn't touch projects
  if (actionResult?.type === "comment-created") {
    return false;
  }
  return defaultShouldRevalidate;
}

export async function loader() {
  // Expensive query, only revalidate if needed
  const projects = await db.project.findMany(); // slow
  return json({ projects });
}

---

Step 11: Use useRevalidator() to manually trigger revalidation (e.g. after a timer or WebSocket message)

Input: Component context, revalidation trigger.

Output: All loaders on the page are revalidated.

Call useRevalidator() and invoke revalidator.revalidate() to manually trigger loader reruns. Use this after a timer tick, WebSocket message, or external event that invalidates cached data.

import { useRevalidator, useEffect } from "@remix-run/react";

export default function ProjectList() {
  const revalidator = useRevalidator();
  useEffect(() => {
    const interval = setInterval(() => revalidator.revalidate(), 5000);
    return () => clearInterval(interval);
  }, [revalidator]);
  return <div>Projects (auto-refreshing)</div>;
}

---

decision points

Should I use a loader or a useEffect?

Decision 1: Is the data needed for correct first render (SSR, prefetch, after actions)?

• Yes , Use loader + useLoaderData<typeof loader>(). Loaders run on the server before the component tree mounts, so the HTML includes the data. This enables SSR, SEO, and fast first paint.
• No , Go to Decision 2.

Decision 2: Is the fetch driven by post-mount user interaction, a timer, or a subscription (not route entry)?

• Yes , Use useEffect or event handlers. The data is not needed until after the page renders, so fetch it in the browser.
• No , Prefer a loader and automatic revalidation. Do not mirror navigation-driven data fetching inside a useEffect; Remix will revalidate loaders automatically, and manual refetches duplicate that work.

---

Should I use json(), raw Response, or defer()?

Decision 1: Do any returned fields need to stream (slow query, expensive computation) while the rest of the page renders fast?

• Yes , Use defer({ critical: await…, slow: promiseWithoutAwait }) + client-side <Suspense><Await>…</Await></Suspense>. Streaming improves TTFB and user perception.
• No , Go to Decision 2.

Decision 2: Do you need a custom status code, custom headers, or explicit TypedResponse<T> typing?

• Yes , Use json(data, init) with init = { status: 400, headers: {...} } (or redirect(url, init) for 3xx). json() is the documented contract for structured data in v2.
• No , Go to Decision 3.

Decision 3: Do you need a non-JSON body (binary file, plain text, CSV, streamed stream)?

• Yes , Build a raw new Response(body, init) with the appropriate Content-Type header.
• No , Default to json(data). It sets application/json, infers clean types for useLoaderData, and is the documented v2 contract.

---

Should I use <Form> posting to an action, or useFetcher?

**