existential-birds/beagle / plugins/beagle-react/skills/remix-v2-routing-review
remix-v2-routing-review
VerifiedReviews Remix v2 route files for naming convention violations, missing layouts, resource-route shape, and v1 holdovers. Use when reviewing files under app/routes/ in a Remix v2 codebase.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
| references/layouts-outlets.md | markdown | 5.9 KB |
| references/resource-routes.md | markdown | 5.9 KB |
| references/root-shell.md | markdown | 4.6 KB |
| references/route-files.md | markdown | 7.5 KB |
| references/v1-holdovers.md | markdown | 6.1 KB |
references/route-files.md
View on GitHub# Route File Naming Smells
Flat-routes v2 reads filenames literally: dots become URL slashes, `_` prefixes hide segments, brackets escape, and anything under `app/routes/` without a folder wrapper is treated as a route module. The smells below are violations of that grammar.
See [remix-v2-routing](../../remix-v2-routing/SKILL.md) for the canonical filename table.
---
## `index.tsx` instead of `_index.tsx`
**Pattern**: A file named `index.tsx` (no leading underscore) under `app/routes/` in a v2 project.
**Why bad**: In v2 flat-routes, `index.tsx` is interpreted as a literal URL segment, producing `/index`. The leading underscore is what marks it as an index route. Files left over from a v1 codebase silently route to the wrong URL after upgrade.
**Fix**:
```text
# Before
app/routes/index.tsx → /index (wrong)
app/routes/concerts/index.tsx → /concerts/index (wrong, also v1 folder shape)
# After
app/routes/_index.tsx → /
app/routes/concerts._index.tsx → /concerts
```
---
## `__double` underscore folders (v1 pathless layouts)
**Pattern**: A folder under `app/routes/` named `__auth/`, `__app/`, etc., containing route files.
**Why bad**: v1 used double-underscore *folders* for pathless layouts (`app/routes/__auth/login.tsx`). v2 flat-routes uses a single-underscore *file* (`app/routes/_auth.tsx` + `app/routes/_auth.login.tsx`). v2's filesystem walker does not recognize the double-underscore folder convention — the routes either fail to mount or mount with the wrong URL.
**Fix**:
```text
# Before (v1)
app/routes/__auth/login.tsx → expected /login under shared layout
app/routes/__auth/signup.tsx
# After (v2)
app/routes/_auth.tsx → pathless layout module with <Outlet />
app/routes/_auth.login.tsx → /login (inherits _auth)
app/routes/_auth.signup.tsx → /signup (inherits _auth)
```
If the v1 tree must stay during migration, wire `@remix-run/v1-route-convention` in `remix.config.js` — see [references/v1-holdovers.md](v1-holdovers.md). Don't flag double-underscore folders when the adapter is installed.
---
## Wrong escape syntax for literal characters
**Pattern**: Attempting to escape a literal dot, dollar, or other convention character with a backslash, quotes, or HTML entities.
```text
sitemap\.xml.tsx # backslash — no
"sitemap.xml".tsx # quotes — no
$bill.tsx # author meant literal /$bill but $ is a dynamic param marker
```
**Why bad**: Only `[...]` brackets escape convention characters in v2. Anything else leaves the special character active — the dot becomes a path delimiter, the `$` becomes a dynamic segment (`$bill.tsx` matches `/anything` and stores it under `params.bill`).
**Fix**: Wrap the literal character(s) in brackets.
```text
sitemap[.]xml.tsx → /sitemap.xml
reports.$id[.pdf].tsx → /reports/:id.pdf
[$]bill.tsx → /$bill (literal dollar sign in URL)
```
Splat misuse (`$.tsx` placed somewhere it shouldn't be) is a separate smell — it is the *correct* escape for "catch the rest", not a literal-character problem. See [resource-routes.md](resource-routes.md) for splat-key errors.
---
## Dot vs underscore confusion
**Pattern**: Using a dot where an underscore was meant (or vice versa), creating routes that don't match the URL the author wrote in the comment.
```text
_auth.login.tsx → /login (correct — pathless _auth, child login)
_auth_login.tsx → /_auth_login (literal — author probably wanted /login)
_auth/login.tsx → ignored or broken (v1-style folder, no route.tsx)
auth._login.tsx → /auth/_login (leading underscore on child is a hidden index)
```
**Why bad**: Each character is grammar:
- `.` = URL slash and parent nesting
- `_` prefix = pathless (no URL contribution) or index marker
- `_` suffix on a segment = opt-out of layout nesting
Mixing them produces URLs that don't match intent and routes that miss their layout.
**Fix**: Pick the right grammar. Quick guide:
| Goal | Filename | URL |
|-----------------------------------------|---------------------------|--------------------|
| URL with shared layout | `parent.child.tsx` | `/parent/child` |
| URL **without** shared layout | `parent_.child.tsx` | `/parent/child` |
| Shared layout, **no** URL segment | `_auth.tsx` + `_auth.x.tsx` | `/x` |
| Index under a layout | `parent._index.tsx` | `/parent` |
---
## Non-route files directly under `app/routes/`
**Pattern**: CSS, server-only helpers, test files, or component files placed at `app/routes/something.css`, `app/routes/utils.server.ts`, `app/routes/Chart.test.tsx`, etc.
**Why bad**: Remix's filesystem walker treats every file in `app/routes/` as a route module unless told otherwise. Non-route files surface as build warnings, mount as broken routes, or land at unexpected URLs.
**Fix**: Either move into a folder with a `route.tsx`, or list them in `ignoredRouteFiles`.
```text
# Folder convention — only route.tsx becomes a route
app/routes/dashboard/
route.tsx
queries.server.ts # not a route
Chart.tsx # not a route
Chart.test.tsx # not a route
```
```js
// remix.config.js — ignore by glob
/** @type {import('@remix-run/dev').AppConfig} */
export default {
ignoredRouteFiles: ["**/.*", "**/*.css", "**/*.test.*", "**/*.server.*"],
};
```
Vite-based v2 projects use `vite.config.ts` with the Remix Vite plugin instead of `remix.config.js`.
---
## Trailing-underscore opt-out with no layout to escape
**Pattern**: A file named `admin_.users.tsx` when no sibling `admin.tsx` (parent layout) exists.
**Why bad**: The trailing underscore is meaningful only when there is a parent layout to skip. Without one, the underscore is noise — reviewers waste time looking for the layout it's escaping. Also signals the author misunderstands the grammar, which often hides a deeper routing bug.
**Fix**: Drop the trailing underscore. Or, if a parent layout *should* exist, add it (`admin.tsx`).
```text
# Smell
app/routes/admin_.users.tsx # no admin.tsx exists
# Fix
app/routes/admin.users.tsx
```
---
## Optional segments `($lang)` without narrowing in the loader
**Pattern**: A route uses an optional segment like `($lang)._index.tsx` and the loader uses `params.lang` without checking for `undefined`.
```tsx
// app/routes/($lang)._index.tsx — smell
export async function loader({ params }: LoaderFunctionArgs) {
const messages = await loadMessages(params.lang); // undefined on /
return json(messages);
}
```
**Why bad**: Optional segments are *optional* — `params.lang` is `string | undefined`. On `/` (no lang), it is `undefined`; on `/en`, it is `"en"`. Passing `undefined` downstream silently produces wrong data, a 500, or a redirect loop.
**Fix**: Narrow before use — default, redirect, or 404.
```tsx
// app/routes/($lang)._index.tsx — correct
export async function loader({ params }: LoaderFunctionArgs) {
const lang = params.lang ?? "en";
const messages = await loadMessages(lang);
return json(messages);
}
```
---
## Verification
For each route-file smell:
1. List the path (`app/routes/<file>`).
2. Quote the literal filename.
3. Confirm v2 (see Hard gate 3 in [SKILL.md](../SKILL.md)).
4. Cross-check against `remix.config.js` — `@remix-run/v1-route-convention` and `ignoredRouteFiles` change which files are legitimate.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |