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/actions.md
View on GitHub# Actions
Actions are server-only handlers for non-GET requests (POST, PUT, PATCH, DELETE) targeting a route. They are where data mutations live. Actions and loaders co-locate in the same route module: "loader = read, action = write."
## Signature
```ts
import { type ActionFunctionArgs } from "@remix-run/node";
export async function action(
{ request, params, context }: ActionFunctionArgs,
): Promise<Response> {
// ...
}
```
Deprecated alias still exported by `@remix-run/node` in 2.x — prefer the v2 name (`LoaderFunctionArgs` / `ActionFunctionArgs`).
## Parsing FormData
```ts
export async function action({ request }: ActionFunctionArgs) {
const form = await request.formData();
const title = form.get("title");
// ...
}
```
`request.formData()` returns a standard `FormData`. Every value is `FormDataEntryValue` (`string | File`) — never trust the static type, always validate. Type assertions like `form.get("title") as string` hide injection and type-confusion bugs.
## Validation with zod (or valibot)
Server-side validation is mandatory; client validation can always be bypassed.
```tsx
// app/routes/projects.new.tsx
import { json, redirect, type ActionFunctionArgs } from "@remix-run/node";
import { useActionData, Form } from "@remix-run/react";
import { z } from "zod";
const NewProject = z.object({
title: z.string().min(1).max(120),
description: z.string().max(2000).optional(),
});
export async function action({ request }: ActionFunctionArgs) {
const form = await request.formData();
const parsed = NewProject.safeParse(Object.fromEntries(form));
if (!parsed.success) {
return json(
{
errors: parsed.error.flatten().fieldErrors,
values: Object.fromEntries(form),
},
{ status: 400 },
);
}
const project = await db.project.create({ data: parsed.data });
return redirect(`/projects/${project.id}`);
}
```
Two important moves above:
1. **Return a 400 on validation failure** so the form route still renders and the user sees inline errors.
2. **Echo `values` back** so the form can rehydrate after a failed submit.
valibot follows the same shape; substitute `safeParse` / `flatten()` equivalents per its API.
## Typed `useActionData`
```tsx
export default function NewProject() {
const actionData = useActionData<typeof action>();
return (
<Form method="post">
<input name="title" defaultValue={(actionData?.values?.title as string) ?? ""} />
{actionData?.errors?.title && <p role="alert">{actionData.errors.title}</p>}
<button type="submit">Create</button>
</Form>
);
}
```
`useActionData<typeof action>()` returns `SerializeFrom<typeof action> | undefined`. The same serialization rules from loaders apply (Dates become strings, undefined is stripped). It is **scoped to the current route** — it cannot read data from parent or child actions. To share an action result up or down the tree, lift the action to a higher route or use a `useFetcher` with a `key`.
## Redirect-After-Success (PRG)
The Post/Redirect/Get pattern is the v2 default for successful mutations: an action that returns a `redirect()` causes the browser to navigate to the target route, which prevents accidental re-submission on refresh and naturally surfaces the freshly mutated state.
```ts
const project = await db.project.create({ data: parsed.data });
return redirect(`/projects/${project.id}`);
```
If you want to stay on the same route after success (e.g. an inline editor), return `json({ ok: true, project })` instead — but then you own pending UI and reset logic via `useActionData`.
## Error Returns vs Throws
| Outcome | Mechanism | Where it surfaces |
|----------------------|--------------------------------------------------------|--------------------------------------|
| Validation error | `return json({ errors }, { status: 400 })` | `useActionData<typeof action>()` |
| Auth failure | `throw redirect("/login")` | Browser navigation |
| 404 / 403 | `throw new Response(..., { status: 404 })` or `throw json({...}, { status: 404 })` | `ErrorBoundary` via `useRouteError()` |
| Unexpected exception | Unhandled throw (any `Error`) | `ErrorBoundary` (no `status` field) |
An `action` that returns `null` / `undefined` with no error handling is an anti-pattern: `useActionData()` is `undefined`, errors are silently swallowed, and the user sees nothing. Either throw to the boundary or return `json({ error })` and render it.
## Index Route Actions
Only the deepest matching action runs. When a parent layout and its index child both define an action, target the index explicitly:
```tsx
<Form action="/things?index" method="post" />
```
Without `?index`, the layout action wins.
## Fetcher Actions (No Navigation)
For inline edits, list-row toggles, and optimistic UI, post to a route action without a URL change via `useFetcher`:
```tsx
import { useFetcher } from "@remix-run/react";
export function StarButton({ project }: { project: Project }) {
const fetcher = useFetcher<typeof action>();
// Predict the next state from in-flight FormData for optimistic UI.
const starred = fetcher.formData
? fetcher.formData.get("starred") === "1"
: project.starred;
return (
<fetcher.Form method="post" action={`/projects/${project.id}/star`}>
<input type="hidden" name="starred" value={starred ? "0" : "1"} />
<button aria-pressed={starred}>{starred ? "★" : "☆"}</button>
</fetcher.Form>
);
}
```
After the fetcher resolves, Remix automatically revalidates affected loaders.
## File Uploads
`request.formData()` returns a `File` for `<input type="file">` fields. For large uploads, prefer `unstable_parseMultipartFormData` with `unstable_createFileUploadHandler` or `unstable_createMemoryUploadHandler` from `@remix-run/node` — the bare `request.formData()` buffers the entire body in memory.
## Don't Hit Actions With Manual `fetch()`
Calling `fetch("/projects/123/star", { method: "POST" })` from a component bypasses revalidation, pending state, progressive enhancement, and CSRF affordances built into `<Form>` and `useFetcher`. Use `useFetcher().submit()` or `useFetcher().load()` instead — same UX without a URL change, and Remix wires up the lifecycle for you.
## Pending State on Submit
```tsx
import { useNavigation, Form } from "@remix-run/react";
export default function SaveButton() {
const nav = useNavigation();
// POST flow: idle → submitting → loading → idle. GET: idle → loading → idle.
// formMethod is UPPERCASE in v2.
const busy = nav.state !== "idle" && nav.formMethod === "POST";
return (
<Form method="post">
<button type="submit" disabled={busy}>
{busy ? "Saving…" : "Save"}
</button>
</Form>
);
}
```
Missing pending UI is a real UX bug — users double-click and double-submit. Gate on `nav.state !== "idle"` (or `fetcher.state !== "idle"` for non-navigating mutations).
For `useFetcher`, `submitting` applies to BOTH GET (`<fetcher.Form method='get'>` and `fetcher.submit(..., {method:'get'})`) and non-GET; only `fetcher.load()` skips `submitting`. This is the inverse of `useNavigation`, which skips `submitting` for GET.
## Action Anti-Pattern Recap
- **No server-side validation** — client validation is bypassable; always re-validate on the server with zod / valibot and return `{ status: 400 }` on failure.
- **`form.get("title") as string`** — `FormDataEntryValue` is `string | File`; type assertions hide injection bugs. Parse with `Object.fromEntries(form)` and a schema.
- **Returning `null` from an action** — `useActionData()` becomes `undefined` and errors are silently swallowed. Either `throw json({ message }, { status: 500 })` to hit `ErrorBoundary` or `return json({ error })`.
- **No redirect after success** — re-rendering the same form route on success risks accidental re-submission on refresh. Redirect via PRG unless you have a specific reason to stay.
- **Manual `fetch()` instead of `useFetcher`** — bypasses revalidation, pending state, and progressive enhancement.
- **Forgetting `?index`** when posting from a layout to its index action — the layout action runs instead.
## Cross-Reference
- Loader-side details: see [loaders.md](loaders.md) for `useLoaderData<typeof loader>()` typing, `redirect()` semantics, and sensitive-data filtering — the same rules apply to action returns.
- Pending UI and revalidation: see [revalidation.md](revalidation.md) for `useNavigation`, `useFetcher`, `useRevalidator`, `shouldRevalidate`, and the v1 → v2 `useTransition` rename.
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 |