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/layouts-outlets.md
View on GitHub# Layouts and Outlets
Parent route modules must render `<Outlet />` so children can mount inside them. Pathless layouts (`_auth.tsx`) wrap URLs without adding a segment. Misuse shows up as blank pages, duplicated chrome, and dotted routes whose authors *thought* there was a layout.
See [remix-v2-routing](../../remix-v2-routing/SKILL.md) for canonical layout shape.
---
## Parent module missing `<Outlet />`
**Pattern**: A route module that has dotted child routes (`concerts.$city.tsx`, `concerts._index.tsx`) but its parent (`concerts.tsx`) does not render `<Outlet />`.
```tsx
// app/routes/concerts.tsx — smell
import { useLoaderData } from "@remix-run/react";
export default function ConcertsLayout() {
const data = useLoaderData<typeof loader>();
return (
<section>
<nav>{/* subnav */}</nav>
{/* missing <Outlet /> — children never render */}
</section>
);
}
```
**Why bad**: Without `<Outlet />`, the parent renders but children mount nowhere. `/concerts/salt-lake-city` shows the parent chrome and a blank where the city detail should be.
**Fix**:
```tsx
import { Outlet } from "@remix-run/react";
export default function ConcertsLayout() {
return (
<section>
<nav>{/* subnav */}</nav>
<Outlet />
</section>
);
}
```
**Do NOT flag** when the parent module is intentionally a wrapper with fixed content and *no* sibling children exist in `app/routes/`. Check: if no `concerts.*.tsx` siblings exist, the wrapper-only shape may be deliberate (rare; usually a refactor remnant).
---
## Pathless layout that forgets to be a layout
**Pattern**: A `_auth.tsx` module that renders standalone content with no `<Outlet />`, while sibling `_auth.login.tsx` / `_auth.signup.tsx` files exist.
```tsx
// app/routes/_auth.tsx — smell
export default function AuthLayout() {
return <div className="auth-shell"><h1>Sign in</h1></div>;
// no Outlet — /login renders the AuthLayout but never the Login child
}
```
**Why bad**: The pathless parent owns the URL match for `/login`, but its render output replaces the child instead of wrapping it.
**Fix**:
```tsx
import { Outlet } from "@remix-run/react";
export default function AuthLayout() {
return (
<div className="auth-shell">
<Outlet />
</div>
);
}
```
---
## Orphan dotted children with no parent module
**Pattern**: Files like `users.profile.settings.tsx` exist but `users.tsx` and `users.profile.tsx` do not.
```text
app/routes/
users.profile.settings.tsx # exists
users.tsx # missing
users.profile.tsx # missing
```
**Why bad**: The URL `/users/profile/settings` works, but reviewers (and the next developer) will look for a `users.tsx` layout that doesn't exist. The dotted name implies nesting that the filesystem doesn't back up.
**Fix**: Either add the missing parent layouts, or use trailing-underscore segments to make the flat intent explicit:
```text
# Make nesting real
app/routes/users.tsx
app/routes/users.profile.tsx
app/routes/users.profile.settings.tsx
# Or make flatness explicit
app/routes/users_.profile_.settings.tsx → /users/profile/settings (flat)
```
---
## Duplicated layout chrome in every child
**Pattern**: Each child route (`dashboard.home.tsx`, `dashboard.billing.tsx`, `dashboard.team.tsx`) renders the same header/sidebar JSX inline instead of pulling it from a parent.
```tsx
// app/routes/dashboard.home.tsx — smell
export default function DashboardHome() {
return (
<div>
<DashboardSidebar /> {/* duplicated */}
<DashboardHeader /> {/* duplicated */}
<main>{/* page content */}</main>
</div>
);
}
```
**Why bad**: Layout duplication causes flash-on-navigation (the chrome unmounts and remounts between sibling routes), keyboard-focus loss, and divergence over time as one copy gets updated and others don't. The whole point of nested routes is that the parent stays mounted.
**Fix**: Lift chrome into `dashboard.tsx` and render `<Outlet />`.
```tsx
// app/routes/dashboard.tsx — single source
import { Outlet } from "@remix-run/react";
export default function DashboardLayout() {
return (
<div>
<DashboardSidebar />
<DashboardHeader />
<main><Outlet /></main>
</div>
);
}
// app/routes/dashboard.home.tsx — child renders only its content
export default function DashboardHome() {
return <h1>Home</h1>;
}
```
---
## `_index` under a pathless parent at root
**Pattern**: A file named `_auth._index.tsx`.
**Why bad**: This renders at `/` wrapped in the `_auth` layout — almost never what was intended. Authors usually want `_auth.login.tsx` (renders at `/login`) or a top-level `_index.tsx` outside the auth shell.
**Fix**: Decide what URL you actually want.
```text
_auth._index.tsx → / (wrapped in AuthLayout) — usually wrong
_auth.login.tsx → /login (wrapped in AuthLayout)
_index.tsx → / (no AuthLayout)
```
---
## Index file at a URL where it conflicts with a sibling
**Pattern**: Both `users.tsx` and `users._index.tsx` rendering content, where `users.tsx` does not render `<Outlet />`.
**Why bad**: `users.tsx` is the layout for the `/users` segment; `users._index.tsx` is the child that renders at exactly `/users`. If the parent doesn't outlet, the index never shows.
**Fix**: Parent renders `<Outlet />`, index renders the at-segment content.
```tsx
// app/routes/users.tsx
import { Outlet } from "@remix-run/react";
export default function UsersLayout() {
return <section><Outlet /></section>;
}
// app/routes/users._index.tsx
export default function UsersIndex() {
return <h1>All users</h1>;
}
```
---
## Verification
For each layout/outlet flag:
1. Quote the relevant module(s) and confirm `<Outlet />` is absent.
2. List the sibling files in `app/routes/` that depend on the parent.
3. Confirm the parent isn't a deliberate wrapper-only (no children → not a layout violation).
4. If pathless: check the URL the file actually produces against the URL the author commented.
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 |