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/conventions.md
View on GitHub# Flat-Routes v2 Conventions
Remix v2 uses a **flat-file** routing convention. Every file under `app/routes/` becomes a route module; the filename itself encodes URL structure, nesting, and special behavior. Dots delimit URL segments, underscores mark pathless/index roles, dollar signs introduce dynamic segments, and brackets escape literal characters.
## Convention Table
| Convention | Syntax | URL / Behavior |
|-----------------------|--------------------------------------|----------------------------------------------------|
| Index route | `_index.tsx`, `concerts._index.tsx` | Renders at the parent's exact URL |
| Dot delimiter | `concerts.trending.tsx` | `/concerts/trending` (also creates parent nesting) |
| Pathless layout | `_auth.tsx`, `_auth.login.tsx` | Shared layout with no URL segment |
| Dynamic segment | `concerts.$city.tsx` | `params.city` |
| Splat (catch-all) | `$.tsx`, `files.$.tsx` | `params["*"]` (matches incl. slashes) |
| Optional segment | `($lang)._index.tsx` | Matches `/` and `/en`; `params.lang` may be undefined |
| Escape literal | `sitemap[.]xml.tsx` | `/sitemap.xml` |
| Folder route | `dashboard/route.tsx` | `/dashboard`; other files in the folder are inert |
| Opt-out of nesting | `concerts_.mine.tsx` | `/concerts/mine`, but does NOT inherit layout |
| Resource route | no `default` export | Returns non-HTML `Response` |
## Index Routes
`_index.tsx` (with the leading underscore) is the v2 index marker. It renders at the **parent's** URL — not its own. So:
```text
app/routes/
_index.tsx → /
concerts.tsx → /concerts (layout)
concerts._index.tsx → /concerts (inside the layout's <Outlet />)
```
A plain `index.tsx` (no underscore) in v2 is treated as a literal `/index` URL. Leftover `index.tsx` files post-upgrade silently produce wrong URLs.
## Dot Delimiter and Nested Layouts
Each dot in a filename creates both a URL slash and a parent/child relationship. The longest matching prefix wins as the parent layout:
```text
app/routes/
concerts.tsx → /concerts (parent — renders <Outlet />)
concerts._index.tsx → /concerts (child)
concerts.$city.tsx → /concerts/:city (child)
concerts.trending.tsx → /concerts/trending
```
If a deeply dotted file has no parent module (e.g. `users.profile.settings.tsx` but no `users.tsx` or `users.profile.tsx`), the route still works — it just has no layout. That can confuse reviewers, so add the parent module or rename with trailing underscores to make the flat intent explicit.
## Pathless Layouts (`_name`)
A single leading underscore makes the segment **pathless** — it adds layout nesting without contributing to the URL:
```text
app/routes/
_auth.tsx (no URL segment; renders <Outlet />)
_auth.login.tsx → /login (inherits _auth)
_auth.signup.tsx → /signup (inherits _auth)
```
```tsx
// app/routes/_auth.tsx
import { Outlet } from "@remix-run/react";
export default function AuthLayout() {
return <div className="auth-shell"><Outlet /></div>;
}
```
Watch out: `_auth._index.tsx` renders at `/` with the auth layout — almost never what was intended. Watch for accidental URL collisions when combining pathless parents with `_index`.
## Dynamic Segments (`$name`)
A segment beginning with `$` captures the URL value under that key in `params`:
```tsx
// app/routes/concerts.$city.tsx → /concerts/salt-lake-city
import type { LoaderFunctionArgs } from "@remix-run/node";
export async function loader({ params }: LoaderFunctionArgs) {
// params.city is `string | undefined` — narrow before use
if (!params.city) throw new Response("Not found", { status: 404 });
return { city: params.city };
}
```
## Splat Route (`$.tsx`)
A literal `$` (no name) catches the rest of the URL, including embedded slashes. The value lives under the `"*"` key, not under `splat` or `rest`:
```tsx
// app/routes/files.$.tsx → /files/anything/here/even/slashes
export async function loader({ params }: LoaderFunctionArgs) {
const path = params["*"]; // bracket access only — there is no named splat
return new Response(await readBlob(path), {
headers: { "Content-Type": "application/octet-stream" },
});
}
```
## Optional Segments (`(segment)`)
Wrapping a segment in parentheses makes it optional:
```text
app/routes/($lang)._index.tsx matches / and /en
```
The key is always present in `params` — just possibly `undefined`. Don't assume it's omitted from the object. If zero-arg and one-arg behavior diverge significantly, prefer two explicit routes over one optional segment.
## Escaping Literal Characters
Only square brackets escape convention characters. Backslashes and quotes do **not** work:
```text
sitemap[.]xml.tsx → /sitemap.xml
reports.$id[.pdf].tsx → /reports/:id.pdf
```
Without the brackets, the dot becomes a nesting delimiter, and `sitemap.xml.tsx` would produce `/sitemap/xml`.
## Folder-Based Co-location
You can promote a folder to a route by placing `route.tsx` inside it. Every other file in the folder is **not** a route — it is colocated source the route imports:
```text
app/routes/
dashboard/
route.tsx ← becomes the route module (/dashboard)
queries.server.ts ← NOT a route
Chart.tsx ← NOT a route
```
Without a `route.tsx`, the folder is ignored entirely. This pattern keeps server helpers, components, and tests next to the route module without polluting the URL space.
## Opt-Out of Layout Nesting (Trailing `_`)
A trailing underscore on a segment keeps the URL nested but **skips** layout inheritance:
```text
app/routes/
concerts.tsx → /concerts (layout)
concerts._index.tsx → /concerts (uses layout)
concerts.$city.tsx → /concerts/:city (uses layout)
concerts_.mine.tsx → /concerts/mine (does NOT use layout)
```
Use sparingly: a trailing underscore signals to readers that you're escaping a parent layout that exists. Don't add it when there's no parent layout to escape — it just creates noise.
## Resource Routes
A route module with **no** `default` export becomes a resource route — it returns a raw `Response` (PDF, JSON, RSS, webhook target) rather than HTML. See [resource-routes.md](resource-routes.md) for full coverage.
## Common Mistakes
- Using v1 `__double` underscore folders or plain `index.tsx` — both silently break in v2.
- Splat reader writing `params.splat` instead of `params["*"]`.
- Escaping a dot with a backslash (`sitemap\.xml.tsx`) instead of brackets.
- Trailing underscore on a route whose parent doesn't exist — pure noise.
- Importing `Outlet`/`Link`/`useLoaderData` from `react-router-dom` instead of `@remix-run/react`.
- Putting CSS, server helpers, or test files directly under `app/routes/` without folder convention — they get treated as routes. Either move into a `feature/` folder or add `ignoredRouteFiles` to `remix.config.js`.
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 |