ESLint Plugin Router
Purpose and Scope
TanStack Router’s developer experience depends on route definitions staying predictable as an application grows. The Router API index shows that route creation, file route creation, navigation, params, search, loader data, route context, and route types are all part of the public surface a user touches when building an app. A router-specific ESLint plugin sits near that workflow: it checks source files before runtime, so common route-definition mistakes are caught while editing or during continuous integration rather than after navigation fails in the browser.
Sources: docs/router/api/router.md
This page focuses on the two router linting concerns called out by the outline: consistent route property ordering and consistency between path parameter names and the code that reads them. Those checks are useful because TanStack Router encourages declarative route options, strongly typed params, route-scoped loaders, and typed navigation. When a route object is organized consistently, reviewers can find path, loader, component, validation, and error options quickly. When parameter names are consistent, links, loaders, hooks, and route APIs all agree about the same URL contract.
Sources: docs/router/api/router.md
Relevant Source Files
- docs/router/api/router.md — Lists the public Router API categories that router linting is meant to protect, including route creation functions, navigation components, hooks for params and search, and route-related types.
How the Plugin Fits the Router API
The Router API index is broad: it includes functions for creating root routes, normal routes, file routes, lazy routes, route masks, routers, redirects, not-found errors, and search-param helpers. It also lists components such as Link, Navigate, MatchRoute, Outlet, Await, and boundary components, plus hooks for navigation, location, matches, params, search, loader data, route context, router state, and blockers. A lint plugin does not replace these APIs. Instead, it keeps the source code that feeds them clean enough for the type system and generated route tree to remain trustworthy.
Sources: docs/router/api/router.md
Think of the ESLint plugin as an editing-time guardrail around the route contract. Route property ordering is a readability and maintainability rule: it encourages every route definition to present the same categories in the same sequence. Parameter-name consistency is a correctness rule: it compares the names implied by a route path with the names used in the corresponding route APIs. Both checks matter most in large route trees, where routes often combine params, validated search, loader dependencies, route context, error boundaries, and navigation links.
Sources: docs/router/api/router.md
Core Checks
Route property ordering helps teams avoid route files where important behavior is hidden among unrelated fields. In TanStack Router, a route definition can describe its URL path, its parent relationship, loader behavior, component rendering, error handling, context usage, and other options. The API index points to Route Options and Route Type references, which indicates that these definitions are a public, typed API surface rather than arbitrary objects. A consistent order makes it easier to compare two route files and spot accidental changes during review.
Sources: docs/router/api/router.md
Route parameter name consistency protects the path-to-code connection. The API index includes hooks and types for params, along with route creation functions and navigation APIs. That tells us params are not just strings embedded in a URL; they flow into loaders, components, links, and imperative navigation. If a path segment declares one parameter name while code reads another, the error can ripple through loader data, navigation options, and route matching. A linter can detect that mismatch before the route is exercised manually.
Sources: docs/router/api/router.md
Setup Pattern
The official TanStack ESLint documentation describes a shared, framework-agnostic ESLint configuration package and shows the modern flat-config style with an exported array. Router-specific linting should be layered into that same ESLint workflow rather than treated as a separate build step. In practice, teams usually keep shared JavaScript, TypeScript, import, and Node rules in the base config, then add router rules to the files that contain route definitions or file-based route modules. This keeps general linting reusable while allowing Router-specific checks to target the right source files.
Sources: docs/router/api/router.md
A typical project workflow is to install ESLint for the workspace, include the shared TanStack config if the project already follows TanStack conventions, then enable the router plugin in the application package that owns the route tree. Run linting locally before opening a pull request, and run the same command in continuous integration. The repository root scripts show that this monorepo treats ESLint as one of several verification targets, alongside unit, end-to-end, type, and build checks, which matches the idea that lint rules catch problems early rather than serving as a replacement for tests.
Compact Reference
| Concern | What it protects | Router API areas affected | Practical result |
|---|---|---|---|
| Route property ordering | Consistent structure inside route definitions | Route creation functions, route options, route types | Route files are easier to scan, review, and refactor |
| Route parameter name consistency | Agreement between URL path params and code usage | Params hooks, loaders, links, navigation options, route APIs | Mismatches are reported before runtime navigation |
Execution Flow
When a developer edits a route, the linter reads the source file and applies router-specific rules before the app is built or navigated. For route property ordering, the rule can inspect the route definition shape and report fields that are arranged outside the expected sequence. For parameter consistency, the rule can inspect the route path and compare it with param usage in the same route context. The exact implementation details are plugin-specific, but the reason for the checks is visible in the Router API: route creation, params, links, loaders, and navigation are all connected surfaces.
Sources: docs/router/api/router.md
In a file-based routing app, these checks are especially helpful because routes are often distributed across many small files. A generated route tree and strongly typed route APIs give excellent feedback once generation and type checking run, but ESLint feedback can appear directly in an editor. In a code-based app, the same rules help keep manually assembled route trees consistent. In both cases, the plugin supports the project’s larger goal of type-safe, data-driven navigation by reducing small inconsistencies that would otherwise make the route tree harder to understand.
Sources: docs/router/api/router.md
Related Pages and Next Steps
Start with the Router API Overview when you need the full map of functions, components, hooks, and types that route linting indirectly supports. Read File-Based Routing and Router Plugin and Route Generation if your application relies on generated route trees, because linting works best when it complements generation rather than replacing it. For runtime debugging, pair linting with Devtools and Debug Router Issues. The practical next step is to enable the plugin in the application’s ESLint configuration, run linting during development, and keep the rule set aligned with the route style your team wants enforced.