existential-birds/beagle / plugins/beagle-react/skills/remix-v2-data-flow
remix-v2-data-flow
VerifiedRemix v2 data loading and mutations. Use when writing loaders, actions, deferred data, revalidation logic, or pending state. Triggers on loader, action, useLoaderData, useActionData, json(), defer(), <Await>, shouldRevalidate, useRevalidator, useNavigation, useTransition (v1 holdover).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.8 KB |
| references/actions.md | markdown | 8.6 KB |
| references/defer-await.md | markdown | 7.0 KB |
| references/loaders.md | markdown | 8.3 KB |
| references/revalidation.md | markdown | 8.0 KB |
references/loaders.md
View on GitHub# Loaders
Loaders are server-only data-fetch functions exported from a route module. Remix calls them during SSR and on every client navigation that lands on the route. You never call a loader directly — "Remix will call your loaders for you; in no case should you ever try to call your loader directly."
## Signature
```ts
import { type LoaderFunctionArgs } from "@remix-run/node";
export async function loader(
{ request, params, context }: LoaderFunctionArgs,
): Promise<Response> {
// ...
}
```
- `request` — standard `Request`. Use `new URL(request.url)` to read search params, `request.headers` for cookies / `Authorization`.
- `params` — route params from the file/segment definition. Values are typed `string | undefined` — always guard before passing to a DB query.
- `context` — adapter-supplied context (Cloudflare bindings, Express locals via the Node adapter, etc.).
Deprecated alias still exported by `@remix-run/node` in 2.x — prefer the v2 name (`LoaderFunctionArgs` / `ActionFunctionArgs`).
## Typed `useLoaderData`
```tsx
import { useLoaderData } from "@remix-run/react";
export default function Invoices() {
const { invoices, status } = useLoaderData<typeof loader>();
return <InvoiceList invoices={invoices} activeStatus={status} />;
}
```
`useLoaderData<typeof loader>()` is a **type annotation**, not a `as`-style assertion. Internally it resolves to `SerializeFrom<typeof loader>`, which models the on-the-wire transformation:
- `Date` becomes `string`.
- `Map` and `Set` both serialize to `{}` (no own-enumerable entries).
- `undefined` fields are stripped.
- Class instances lose their methods (just plain data survives).
If your component calls `data.createdAt.getFullYear()`, the type already says `string` — that's a real bug, not a tooling complaint.
## `json()` — Status, Headers, Typing
```ts
import { json } from "@remix-run/node";
return json({ invoices }, { status: 200, headers: { "Cache-Control": "private, max-age=10" } });
return json({ errors }, { status: 400 });
return json({ user }, 201); // numeric shorthand for status
```
`json(data, init?)` is a shortcut for an `application/json` response with the given status and headers. The return type is `TypedResponse<typeof data>` — that's what lets `useLoaderData<typeof loader>()` infer the payload through `SerializeFrom`.
### When `json()` Is Optional in v2
v2 did **not** change the underlying contract: loaders must return a `Response`. `json()` is the ergonomic wrapper. Bare object returns work in v2 (Remix auto-wraps as `json()`), but `json()` is preferred for explicit status, headers, and clean `TypedResponse<T>` typing. Reach for `json()` whenever you need a non-200 status, custom headers, or explicit `TypedResponse<T>` inference.
## `redirect()`
```ts
import { redirect } from "@remix-run/node";
throw redirect("/login");
return redirect(`/projects/${project.id}`, {
headers: { "Set-Cookie": await commitSession(session) },
});
```
`redirect(url, init?)` is a shortcut for 30x responses. Default status is `302`; supports `301` / `303` / `307` and any standard `Response` init (including `Set-Cookie`).
## Throwing for Short-Circuits
Throwing a `Response` exits the data function immediately — useful for auth guards and 404s.
```ts
// app/utils/auth.server.ts
export async function requireUser(request: Request) {
const user = await getUser(request);
if (!user) throw redirect("/login");
return user;
}
// In a loader:
export async function loader({ request }: LoaderFunctionArgs) {
const user = await requireUser(request);
return json({ user });
}
```
Throw `new Response("Not Found", { status: 404 })` or `throw json({ message }, { status: 404 })` for 404s — `useRouteError()` + `isRouteErrorResponse()` will then expose `status` / `statusText` to your `ErrorBoundary`. Throwing a plain `Error` will not classify as a route response.
## Filtering Sensitive Data
Loaders run server-only, but their return values ship to the browser as JSON. Project to a safe DTO before returning.
```ts
// Bad — leaks passwordHash, internal flags
const user = await db.user.findUnique({ where: { id } });
return json({ user });
// Good
const user = await db.user.findUnique({
where: { id },
select: { id: true, email: true, name: true },
});
return json({ user });
```
If you must fetch the full record (to do server-side work), strip before return:
```ts
const full = await db.user.findUnique({ where: { id } });
const { passwordHash, internalNotes, ...safe } = full!;
return json({ user: safe });
```
## Params: Always Guard
`params` values are `string | undefined`. Downstream DB lookups silently coerce or query `undefined`.
```ts
import invariant from "tiny-invariant";
export async function loader({ params }: LoaderFunctionArgs) {
invariant(params.projectId, "projectId required");
const project = await db.project.findUnique({ where: { id: params.projectId } });
if (!project) throw new Response("Not Found", { status: 404 });
return json({ project });
}
```
Or parse with zod for richer shapes:
```ts
const ParamsSchema = z.object({ projectId: z.string().uuid() });
const { projectId } = ParamsSchema.parse(params);
```
## Reading Search Params
```ts
export async function loader({ request }: LoaderFunctionArgs) {
const url = new URL(request.url);
const status = url.searchParams.get("status") ?? "open";
const invoices = await db.invoice.findMany({ where: { status } });
return json({ invoices, status });
}
```
## Don't Mutate in Loaders
Loaders run on every GET and may be invoked speculatively by prefetch; revalidation re-runs them after every action. Any mutation inside a loader will replay. Writes belong in `action`.
## Don't Re-Define Data in Child Loaders
Re-loading the same query in a parent and child means two sources of truth, doubled DB load, and divergent shapes after revalidation. Load once at the highest matching route and read from children via `useMatches` / `useRouteLoaderData`.
## `.server` Suffix
Modules with a `.server.ts` / `.server.tsx` suffix are never bundled to the client. Import DB clients, secrets, and crypto helpers from `~/db.server`, `~/auth.server`, etc., so a stray browser-side import of a server-only utility fails fast at build time rather than leaking secrets.
## Sharing Data Across Routes — `useRouteLoaderData`
When a child route needs data already loaded by an ancestor, don't refetch — read the parent's loader data directly.
```tsx
// app/root.tsx
export async function loader() {
return json({ user: await getCurrentUser() });
}
// app/routes/dashboard.tsx
import { useRouteLoaderData } from "@remix-run/react";
import type { loader as rootLoader } from "~/root";
export default function Dashboard() {
const data = useRouteLoaderData<typeof rootLoader>("root");
return <h1>Welcome, {data?.user.name}</h1>;
}
```
The string id matches the route module's id (`"root"` for `app/root.tsx`; file-based ids for nested routes). Pair with `typeof rootLoader` to keep `SerializeFrom`-aware typing.
## Headers from the Leaf Loader Win
Only the deepest matching `headers` export is used by default; parent caching policies are ignored unless you merge them yourself.
```ts
// app/routes/products.$id.tsx
import type { HeadersFunction } from "@remix-run/node";
export const headers: HeadersFunction = ({ loaderHeaders, parentHeaders }) => ({
"Cache-Control": loaderHeaders.get("Cache-Control") ?? parentHeaders.get("Cache-Control") ?? "no-store",
});
```
## Response Caching
For per-route caching, set `Cache-Control` via the `init` argument to `json()`:
```ts
return json(
{ product },
{
headers: {
"Cache-Control": "private, max-age=60, stale-while-revalidate=300",
},
},
);
```
Choose `private` for user-specific data; `public` only when the response is identical for every viewer.
## Quick Anti-Pattern Recap
- **Fetching in `useEffect` what belongs in a loader** — defeats SSR, creates waterfalls, skips automatic revalidation.
- **Mutating in a loader** — loaders run on GETs and may be prefetched; writes belong in `action`.
- **Returning sensitive fields** — everything goes to the browser as JSON; project to a safe DTO.
- **Reading `params.foo` without guarding** — values are `string | undefined`; use `invariant` or zod.
- **Asserting types instead of annotating** — `useLoaderData<typeof loader>()` is an annotation that drives `SerializeFrom`; never `useLoaderData() as Foo`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |