Chapter 54: ESLint Plugin Router

Core Idea

@tanstack/eslint-plugin-router is TanStack Router's official ESLint plugin that enforces routing-specific best practices, installable via either the modern flat config (eslint.config.js) or the legacy .eslintrc format, and its recommended ruleset should be paired with an override for @typescript-eslint/only-throw-error to allow redirect/notFound throws.

Key Concepts

• @tanstack/eslint-plugin-router: Separate installable package providing router-specific lint rules.
• Flat config recommended setup: import pluginRouter from '@tanstack/eslint-plugin-router' then spreading ...pluginRouter.configs['flat/recommended'] into the exported config array.
• Flat config custom setup: Registering the plugin under plugins: { '@tanstack/router': pluginRouter } and enabling individual rules (e.g. '@tanstack/router/create-route-property-order': 'error').
• Legacy config: .eslintrc equivalent using "extends": ["plugin:@tanstack/eslint-plugin-router/recommended"] or manually listing the plugin and rules.
• create-route-property-order: The plugin's flagship (and currently only listed) rule, covered in depth in the next chapter.
• @typescript-eslint/only-throw-error conflict: This popular typescript-eslint rule (in recommended-type-checked/strict-type-checked) disallows throwing non-Error values, conflicting with TanStack Router's throw redirect(...) / throw notFound() pattern; must be configured with an allow list for Redirect and NotFoundError from @tanstack/router-core.

Code Examples

import pluginRouter from '@tanstack/eslint-plugin-router'

export default [
  ...pluginRouter.configs['flat/recommended'],
  // Any other config...
]

• What it demonstrates: The minimal flat-config setup enabling all recommended TanStack Router lint rules.

{
  "rules": {
    "@typescript-eslint/only-throw-error": [
      "error",
      {
        "allow": [
          { "from": "package", "package": "@tanstack/router-core", "name": "Redirect" },
          { "from": "package", "package": "@tanstack/router-core", "name": "NotFoundError" }
        ]
      }
    ]
  }
}

• What it demonstrates: Reconciling typescript-eslint's only-throw-error rule with TanStack Router's throwable redirect()/notFound() pattern.

Key Takeaways

1. Install and enable flat/recommended (or the legacy equivalent) as the default starting point rather than hand-picking rules.
2. If using typescript-eslint's type-checked rulesets, explicitly allowlist Redirect and NotFoundError in only-throw-error, otherwise every throw redirect()/throw notFound() will trigger a lint error.
3. Individual rules can still be tuned or disabled via the custom config path if the full recommended set is too strict for a project.

Connects To

• Ch 55: create-route Property Order Rule, the detailed spec for the plugin's main rule.
• Ch 50: Not Found Errors, and the redirect() function, both rely on the throw pattern this chapter's ESLint interop addresses.