existential-birds/beagle / plugins/beagle-react/skills/remix-v2-routing
remix-v2-routing
VerifiedRemix v2 routing patterns. Use when implementing flat-routes v2 conventions, route file naming, nested layouts, resource routes, or root.tsx scaffolding. Triggers on _<name>.tsx (pathless layout), _index.tsx, $param, app/routes/, @remix-run/dev, defineRoutes, <Outlet /> in route modules.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| references/conventions.md | markdown | 7.3 KB |
| references/resource-routes.md | markdown | 5.4 KB |
| references/root.md | markdown | 7.3 KB |
| references/v1-migration.md | markdown | 6.2 KB |
references/resource-routes.md
View on GitHub# Resource Routes
A **resource route** is a route module that returns a raw HTTP `Response` instead of HTML. PDFs, sitemaps, RSS feeds, JSON APIs, OAuth callbacks, webhooks, and file downloads are all resource routes.
## The Defining Rule: No `default` Export
A route becomes a resource route when its module has **no `default` export**. That single fact controls everything else about its behavior — there's no decorator, no config flag, no naming convention. The presence or absence of `export default function` is the switch.
```tsx
// app/routes/reports.$id[.pdf].tsx → /reports/42.pdf
import type { LoaderFunctionArgs } from "@remix-run/node";
import invariant from "tiny-invariant";
export async function loader({ params }: LoaderFunctionArgs) {
invariant(params.id, "id is required");
const pdf = await generateReportPDF(params.id);
return new Response(pdf, {
status: 200,
headers: { "Content-Type": "application/pdf" },
});
}
// NOTE: no `export default` — this is what makes it a resource route.
```
If you add a default export — even an empty one — Remix treats this as a UI route and the resource-route fast path disappears.
## What Changes When There's No Default Export
| Behavior | UI route (default export) | Resource route (no default) |
|-----------------------|---------------------------|-----------------------------|
| Response type | HTML document | Raw `Response` |
| Parent loaders run | Yes | **No** |
| `ErrorBoundary` mount | Yes | No (errors propagate) |
| `<Link>` navigation | Client-side | Requires `reloadDocument` |
| Meta / Links / Scripts| Injected | Not injected |
| Hydration | Yes | N/A |
The most important entry: **parent loaders are skipped**. A GET to a resource route does not invoke ancestor loaders. Auth checks that live in a `_layout.tsx` parent will not run. Re-check auth inside the resource route's own loader.
## Linking to Resource Routes
A normal `<Link>` tries to fetch the route the way it would fetch any other Remix route. For a resource route, that yields a parse error or a blank page because Remix is expecting a route-shaped response. Two valid options:
```tsx
import { Link } from "@remix-run/react";
// 1. Force a full document request via Remix's Link
<Link reloadDocument to="/reports/42.pdf">Download</Link>
// 2. Or just use a plain anchor
<a href="/reports/42.pdf">Download</a>
```
`reloadDocument` tells Remix: don't client-route this — let the browser do a regular navigation, which is what binary responses need.
## Example: Sitemap
```tsx
// app/routes/sitemap[.]xml.tsx → /sitemap.xml
import type { LoaderFunctionArgs } from "@remix-run/node";
export async function loader({ request }: LoaderFunctionArgs) {
const url = new URL(request.url);
const xml = await buildSitemap(url.origin);
return new Response(xml, {
status: 200,
headers: {
"Content-Type": "application/xml",
"Cache-Control": "public, max-age=3600",
},
});
}
```
Note the `[.]` bracket-escape on the filename so the dot is treated as a literal character, not a URL-segment delimiter.
## Example: JSON API Endpoint
```tsx
// app/routes/api.users.$id.tsx
import type { LoaderFunctionArgs } from "@remix-run/node";
import { json } from "@remix-run/node";
import invariant from "tiny-invariant";
export async function loader({ params, request }: LoaderFunctionArgs) {
await requireApiKey(request); // parent loaders DID NOT run
invariant(params.id, "id is required");
const user = await getUser(params.id);
if (!user) throw new Response("Not found", { status: 404 });
return json(user);
}
```
`json()` from `@remix-run/node` is a thin wrapper over `new Response(JSON.stringify(...), { headers: { "Content-Type": "application/json" } })` — use it freely in resource routes.
## Example: Webhook Receiver (Action Only)
A resource route can export only `action` if it's purely a write endpoint:
```tsx
// app/routes/webhooks.stripe.tsx
import type { ActionFunctionArgs } from "@remix-run/node";
export async function action({ request }: ActionFunctionArgs) {
if (request.method !== "POST") {
return new Response("Method not allowed", { status: 405 });
}
const event = await verifyStripeSignature(request);
await handleStripeEvent(event);
return new Response(null, { status: 204 });
}
```
No `loader`, no `default` export — GETs will 405 from Remix's default method handling.
## Common Mistakes
- **Default export on a JSON/PDF/webhook route**: Turns it into a UI route. Parent loaders run, an `ErrorBoundary` mounts, Remix expects HTML. Delete the default export.
- **`<Link to="/api/foo.pdf">`** without `reloadDocument`: Client navigation tries to parse the binary as a route module. Returns a parse error or blank page.
- **Relying on auth in a parent layout's loader**: Parent loaders don't run for resource routes. Re-do the auth check inline.
- **Forgetting the bracket escape on dotted URLs**: `sitemap.xml.tsx` produces `/sitemap/xml`, not `/sitemap.xml`. Use `sitemap[.]xml.tsx`.
- **Returning a plain string or object**: Always return a `Response` (or `json(...)`). Returning a string yields `Content-Type: text/html` and a status the browser may not handle correctly for non-HTML payloads.
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 |