existential-birds/beagle / plugins/beagle-react/skills/remix-v2-forms
remix-v2-forms
VerifiedRemix v2 form submissions and mutations. Use when implementing forms, optimistic UI, file uploads, or multi-action routes. Triggers on <Form>, useFetcher, useSubmit, useNavigation for pending state, unstable_parseMultipartFormData, fetcher.formData, intent-based actions, encType multipart.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.6 KB |
| references/fetcher.md | markdown | 6.8 KB |
| references/form.md | markdown | 8.3 KB |
| references/intent-actions.md | markdown | 4.2 KB |
| references/optimistic-ui.md | markdown | 6.1 KB |
| references/uploads.md | markdown | 5.4 KB |
references/uploads.md
View on GitHub# File Uploads
Remix v2 ships file-upload helpers under permanent `unstable_` prefixes.
The API was renamed without the prefix in React Router v7 — in v2 you
keep the prefix. Code that migrates needs to update imports.
## The Three Helpers
| Import | Purpose |
|---|---|
| `unstable_parseMultipartFormData(request, uploadHandler)` | Parse a `multipart/form-data` request body in an action. Returns `Promise<FormData>`. |
| `unstable_createMemoryUploadHandler({ maxPartSize?, filter? })` | In-memory upload handler. Returns a `File`. For small files only. |
| `unstable_createFileUploadHandler({ directory?, maxPartSize?, filter?, file? })` | Disk-backed upload handler. Streams to a directory. For larger files. |
All three live in `@remix-run/node` (or `@remix-run/cloudflare` for the
Cloudflare adapter). The `unstable_` prefix is **permanent in v2** — do
not strip it expecting it to work.
## `encType="multipart/form-data"` Is Mandatory
Without it, `request.formData()` strips file data. `formData.get("avatar")`
returns the filename **string**, not a `File`. The upload silently
fails. Set `encType="multipart/form-data"` on the `<Form>` AND parse via
`unstable_parseMultipartFormData` in the action.
## Pattern: In-Memory Upload (Small Files)
```tsx
// app/routes/avatar.tsx
import {
json,
redirect,
unstable_createMemoryUploadHandler,
unstable_parseMultipartFormData,
type ActionFunctionArgs,
} from "@remix-run/node";
import { Form } from "@remix-run/react";
export async function action({ request }: ActionFunctionArgs) {
const uploadHandler = unstable_createMemoryUploadHandler({
maxPartSize: 500_000, // 500 KB cap; reject larger uploads
});
const formData = await unstable_parseMultipartFormData(request, uploadHandler);
const file = formData.get("avatar");
if (!(file instanceof File)) return json({ error: "No file" }, { status: 400 });
await storeAvatar(file);
return redirect("/account");
}
export default function AvatarRoute() {
return (
<Form method="post" encType="multipart/form-data">
<input type="file" name="avatar" accept="image/*" />
<button>Upload</button>
</Form>
);
}
```
Memory handler is fine for avatars and small attachments (a few hundred
KB). For anything larger, use `unstable_createFileUploadHandler` or
stream directly to object storage.
## Pattern: Disk-Backed Upload
```tsx
import {
unstable_createFileUploadHandler,
unstable_parseMultipartFormData,
type ActionFunctionArgs,
} from "@remix-run/node";
export async function action({ request }: ActionFunctionArgs) {
const uploadHandler = unstable_createFileUploadHandler({
directory: "/tmp/uploads",
maxPartSize: 10_000_000, // 10 MB
file: ({ filename }) => filename,
filter: ({ contentType }) => contentType.startsWith("image/"), // callbacks also receive `name`
});
const formData = await unstable_parseMultipartFormData(request, uploadHandler);
const upload = formData.get("attachment");
// upload is a NodeOnDiskFile — has .name, .size, .type, and .getFilePath()
// Move it to permanent storage, then delete the temp file.
return json({ ok: true });
}
```
`unstable_createFileUploadHandler` streams the part to disk. The returned
file object exposes the temp path; move or stream from there to your
permanent store, then clean up.
## Bound Every Handler
**`unstable_createMemoryUploadHandler`** has no default cap — without `maxPartSize`, it buffers the entire upload into RAM. **`unstable_createFileUploadHandler`** defaults `maxPartSize` to 3MB, which is usually still too generous for untrusted user input. Always set an explicit `maxPartSize` matched to the upload's purpose.
`filter` is the second line of defense: reject parts whose `contentType`
or `name` doesn't match what you accept.
```ts
const uploadHandler = unstable_createMemoryUploadHandler({
maxPartSize: 500_000,
filter: ({ contentType, name }) =>
name === "avatar" && contentType.startsWith("image/"),
});
```
## Anti-Patterns
- **`<Form method="post">` with `<input type="file">` but no `encType`.**
The file silently isn't sent; `formData.get("avatar")` returns the
filename string. Set `encType="multipart/form-data"`.
- **`unstable_createMemoryUploadHandler()` with no `maxPartSize`.**
Unbounded RAM buffering — OOM risk. Always bound.
- **Stripping the `unstable_` prefix in v2.** The prefix is permanent in
Remix v2; only React Router v7 renamed these without it.
- **Using the memory handler for user-uploaded photos / documents.**
Anything over ~1 MB should stream to disk or object storage.
- **Trusting `file.name` or `file.type` as security boundaries.** Both
are user-controlled. Validate magic bytes, scan content, or run
uploads through a trusted processor.
## Gotchas
- `unstable_parseMultipartFormData` returns the parsed `FormData`. Use
`formData.get(name) instanceof File` to discriminate text fields from
uploads — `get` can return string, File, or null.
- Mixed forms (text fields + file inputs) work fine: text fields pass
through `formData` as strings; only file inputs invoke the upload
handler.
- The Cloudflare adapter (`@remix-run/cloudflare`) re-exports these
helpers with the same `unstable_` names. Node and Cloudflare imports
are interchangeable at the type level but pick one matching your
runtime.
- Upload handlers run on the server. The `request` object cannot be
consumed twice — call `unstable_parseMultipartFormData(request, ...)`
exactly once per action.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |