Remix v2 Routing Code Review#

Loaded by review-remix-v2 (umbrella) to flag routing anti-patterns in app/routes/ modules. See remix-v2-routing for canonical patterns.

Quick Reference#

Issue TypeReferenceFilename smells ( index.tsx, __auth, wrong escape, non-route files)references/route-files.mdMissing <Outlet />, orphan dotted segments, duplicated layout logicreferences/layouts-outlets.mdDefault export on a resource, <Link> without reloadDocument, splat paramsreferences/resource-routes.mdreact-router-dom imports, __double folders, v1-adapter fallbackreferences/v1-holdovers.mdMissing <Meta />/ <Links />/ <Scripts />/ <ScrollRestoration />, Vite-vs-Classic <LiveReload />, root ErrorBoundary without document shellreferences/root-shell.md

Scope#

This skill flags issues in:

• Files under app/routes/ (filenames, exports, imports, JSX shape)
• app/root.tsx (document shell, root <Outlet />)
• remix.config.js (entries that change route discovery: routes(), ignoredRouteFiles, @remix-run/v1-route-convention)
• Any module that links to a resource route ( <Link> usage)

Out of scope: loader/action data contracts (covered by remix-v2-data-flow-review), form behavior ( remix-v2-forms-review), meta/headers ( remix-v2-meta-sessions-review).

Review Checklist#

• Index routes named _index.tsx, not index.tsx
• Pathless layouts use single underscore ( _auth.tsx), not double ( __auth/)
• Dotted child routes ( users.profile.tsx) have a parent module or use trailing underscore ( users_.profile.tsx)
• Parent route modules render <Outlet />
• Splat segments read params["*"], never params.splat / params.rest
• Literal dots/special chars escaped with brackets ( sitemap[.]xml.tsx)
• Resource routes have no default export
• <Link> to a resource route uses reloadDocument (or is a plain <a>)
• Imports come from @remix-run/react, not react-router-dom
• Non-route files (CSS, helpers, tests) live in a folder with route.tsx, or are listed in ignoredRouteFiles
• Trailing-underscore opt-outs only used when a parent layout actually exists to escape
• Optional segments ($lang) narrow params.lang in the loader (see references/route-files.md)

Valid Patterns (Do NOT Flag)#

• Resource route with no default export — this is the convention that makes it a resource route. Never flag.
• Any _-prefixed pathless layout file without <Outlet /> when the module is intentionally a wrapper that renders fixed UI only. Confirm by checking children — if no *.{segment}.tsx siblings exist, the wrapper-only shape is intentional.
• Files prefixed with _ that don't appear in any URL — pathless layouts and _index are supposed to be hidden from the URL.
• @remix-run/v1-route-convention wired up in remix.config.js — legitimate migration adapter, not a smell on its own. Only flag if v1-style files appear without the adapter installed.
• useLoaderData<typeof loader>() — type annotation, not assertion.
• Splat route accessing params["*"] with bracket syntax — that is the only correct access pattern.
• Folder app/routes/dashboard/ with route.tsx plus sibling .server.ts, .css, component files — co-location is the documented pattern.
• Trailing underscore ( concerts_.mine.tsx) when a sibling concerts.tsx layout exists and this URL intentionally skips it.

Context-Sensitive Rules#

Only flag these issues when the specific context applies:

IssueFlag ONLY IFindex.tsx under app/routes/Project is v2 and @remix-run/v1-route-convention is NOT wired in remix.config.jsParent module without <Outlet />Sibling dotted children ( parent.*.tsx) exist in app/routes/``__double underscore folderNo v1-convention adapter is installedTrailing-underscore segmentNo corresponding parent layout exists (nothing to opt out of)Default export on a module returning non-HTMLThe loader/action actually returns a raw Response (PDF, JSON, RSS)<Link> to resource routeTarget route has no default export AND <Link> lacks reloadDocument

Hard gates (before writing findings)#

Run these in order. Do not draft user-facing findings until every gate passes for the batch you are about to report.

1. Location evidence — Pass: Each issue lists a repo path (file under app/routes/ or remix.config.js) and either a line range or a short verbatim quote from the file you read. Filename-only smells must quote the literal filename.

2. Exemption check — Pass: For each issue, state in one line why it is not covered by Valid Patterns (Do NOT Flag). Resource-route flags require explicit evidence of a default export or a <Link> without reloadDocument.

3. Version check — Pass: Confirm the project is Remix v2 (check package.json for @remix-run/react ^2, or presence of v2 flat-routes filenames elsewhere in app/routes/). If @remix-run/v1-route-convention is wired in remix.config.js, v1 filenames ( __auth/, index.tsx) are intentional — do not flag them as smells.

4. Protocol — Pass: Complete the Pre-Report Verification Checklist in review-verification-protocol for this review.

When to Load References#

• Reviewing filenames under app/routes/ → references/route-files.md
• Reviewing parent modules and shared chrome → references/layouts-outlets.md
• Reviewing a module that returns non-HTML, or any <Link> to such a module → references/resource-routes.md
• Reviewing imports or filenames that look like v1 → references/v1-holdovers.md
• Reviewing app/root.tsx (document shell, <Meta />/ <Links />/ <Scripts />/ <ScrollRestoration />, <LiveReload /> on Vite vs Classic Compiler, root ErrorBoundary) → references/root-shell.md

Review Questions#

1. Does every parent route render <Outlet />, or is it a deliberate wrapper-only?
2. Do filenames match the v2 grammar (single _ for pathless, _index for index, [...] for escapes)?
3. Are resource routes free of default exports, and do all <Link> s to them use reloadDocument?
4. Are all router imports from @remix-run/react (and server helpers from @remix-run/node)?
5. If v1 filenames exist, is @remix-run/v1-route-convention wired up — or are they accidental?

Additional Documentation#

• Route file naming smells: references/route-files.md — index.tsx, __double folders, wrong escape syntax, dot/underscore confusion, non-route files under app/routes/.
• Layouts and outlets: references/layouts-outlets.md — pathless layout misuse, missing <Outlet />, orphan dotted children, duplicated layout logic.
• Resource routes: references/resource-routes.md — accidental default export, <Link> without reloadDocument, splat params["*"] access.
• v1 holdovers: references/v1-holdovers.md — react-router-dom imports, __auth folders, @remix-run/v1-route-convention as a deliberate-vs-accidental tell.