@tanstack/eslint-plugin-router 1.141.0 → 1.155.0

package/dist/esm/rules/route-param-names/route-param-names.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-param-names.utils.js","sources":["../../../../src/rules/route-param-names/route-param-names.utils.ts"],"sourcesContent":["import { VALID_PARAM_NAME_REGEX } from './constants'\n\nexport interface ExtractedParam {\n  /** The full param string including $ prefix (e.g., \"$userId\", \"-$optional\") */\n  fullParam: string\n  /** The param name without $ prefix (e.g., \"userId\", \"optional\") */\n  paramName: string\n  /** Whether this is an optional param (prefixed with -$) */\n  isOptional: boolean\n  /** Whether this param name is valid */\n  isValid: boolean\n}\n\n/**\n * Extracts param names from a route path segment.\n *\n * Handles these patterns:\n * - $paramName                     -> extract \"paramName\"\n * - {$paramName}                   -> extract \"paramName\"\n * - prefix{$paramName}suffix       -> extract \"paramName\"\n * - {-$paramName}                  -> extract \"paramName\" (optional)\n * - prefix{-$paramName}suffix      -> extract \"paramName\" (optional)\n * - $ or {$}                       -> wildcard, skip validation\n */\nexport function extractParamsFromSegment(\n  segment: string,\n): Array<ExtractedParam> {\n  const params: Array<ExtractedParam> = []\n\n  // Skip empty segments\n  if (!segment || !segment.includes('$')) {\n    return params\n  }\n\n  // Check for wildcard ($ alone or {$})\n  if (segment === '$' || segment === '{$}') {\n    return params // Wildcard, no param name to validate\n  }\n\n  // Pattern 1: Simple $paramName (entire segment starts with $)\n  if (segment.startsWith('$') && !segment.includes('{')) {\n    const paramName = segment.slice(1)\n    if (paramName) {\n      params.push({\n        fullParam: segment,\n        paramName,\n        isOptional: false,\n        isValid: VALID_PARAM_NAME_REGEX.test(paramName),\n      })\n    }\n    return params\n  }\n\n  // Pattern 2: Braces pattern {$paramName} or {-$paramName} with optional prefix/suffix\n  // Match patterns like: prefix{$param}suffix, {$param}, {-$param}\n  const bracePattern = /\\{(-?\\$)([^}]*)\\}/g\n  let match\n\n  while ((match = bracePattern.exec(segment)) !== null) {\n    const prefix = match[1] // \"$\" or \"-$\"\n    const paramName = match[2] // The param name after $ or -$\n\n    if (!paramName) {\n      // This is a wildcard {$} or {-$}, skip\n      continue\n    }\n\n    const isOptional = prefix === '-$'\n\n    params.push({\n      fullParam: `${prefix}${paramName}`,\n      paramName,\n      isOptional,\n      isValid: VALID_PARAM_NAME_REGEX.test(paramName),\n    })\n  }\n\n  return params\n}\n\n/**\n * Extracts all params from a route path.\n *\n * @param path - The route path (e.g., \"/users/$userId/posts/$postId\")\n * @returns Array of extracted params with validation info\n */\nexport function extractParamsFromPath(path: string): Array<ExtractedParam> {\n  if (!path || !path.includes('$')) {\n    return []\n  }\n\n  const segments = path.split('/')\n  const allParams: Array<ExtractedParam> = []\n\n  for (const segment of segments) {\n    const params = extractParamsFromSegment(segment)\n    allParams.push(...params)\n  }\n\n  return allParams\n}\n\n/**\n * Validates a single param name.\n *\n * @param paramName - The param name to validate (without $ prefix)\n * @returns Whether the param name is valid\n */\nexport function isValidParamName(paramName: string): boolean {\n  return VALID_PARAM_NAME_REGEX.test(paramName)\n}\n\n/**\n * Gets all invalid params from a route path.\n *\n * @param path - The route path\n * @returns Array of invalid param info\n */\nexport function getInvalidParams(path: string): Array<ExtractedParam> {\n  const params = extractParamsFromPath(path)\n  return params.filter((p) => !p.isValid)\n}\n"],"names":[],"mappings":";AAwBO,SAAS,yBACd,SACuB;AACvB,QAAM,SAAgC,CAAA;AAGtC,MAAI,CAAC,WAAW,CAAC,QAAQ,SAAS,GAAG,GAAG;AACtC,WAAO;AAAA,EACT;AAGA,MAAI,YAAY,OAAO,YAAY,OAAO;AACxC,WAAO;AAAA,EACT;AAGA,MAAI,QAAQ,WAAW,GAAG,KAAK,CAAC,QAAQ,SAAS,GAAG,GAAG;AACrD,UAAM,YAAY,QAAQ,MAAM,CAAC;AACjC,QAAI,WAAW;AACb,aAAO,KAAK;AAAA,QACV,WAAW;AAAA,QACX;AAAA,QACA,YAAY;AAAA,QACZ,SAAS,uBAAuB,KAAK,SAAS;AAAA,MAAA,CAC/C;AAAA,IACH;AACA,WAAO;AAAA,EACT;AAIA,QAAM,eAAe;AACrB,MAAI;AAEJ,UAAQ,QAAQ,aAAa,KAAK,OAAO,OAAO,MAAM;AACpD,UAAM,SAAS,MAAM,CAAC;AACtB,UAAM,YAAY,MAAM,CAAC;AAEzB,QAAI,CAAC,WAAW;AAEd;AAAA,IACF;AAEA,UAAM,aAAa,WAAW;AAE9B,WAAO,KAAK;AAAA,MACV,WAAW,GAAG,MAAM,GAAG,SAAS;AAAA,MAChC;AAAA,MACA;AAAA,MACA,SAAS,uBAAuB,KAAK,SAAS;AAAA,IAAA,CAC/C;AAAA,EACH;AAEA,SAAO;AACT;AAQO,SAAS,sBAAsB,MAAqC;AACzE,MAAI,CAAC,QAAQ,CAAC,KAAK,SAAS,GAAG,GAAG;AAChC,WAAO,CAAA;AAAA,EACT;AAEA,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,QAAM,YAAmC,CAAA;AAEzC,aAAW,WAAW,UAAU;AAC9B,UAAM,SAAS,yBAAyB,OAAO;AAC/C,cAAU,KAAK,GAAG,MAAM;AAAA,EAC1B;AAEA,SAAO;AACT;AAkBO,SAAS,iBAAiB,MAAqC;AACpE,QAAM,SAAS,sBAAsB,IAAI;AACzC,SAAO,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO;AACxC;"}

package/dist/esm/rules.js

@@ -1,5 +1,7 @@
-import { rule, name } from "./rules/create-route-property-order/create-route-property-order.rule.js";
+import { rule as rule$1, name as name$1 } from "./rules/create-route-property-order/create-route-property-order.rule.js";
+import { rule, name } from "./rules/route-param-names/route-param-names.rule.js";
 const rules = {
+  [name$1]: rule$1,
   [name]: rule
 };
 export {

package/dist/esm/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sources":["../../src/rules.ts"],"sourcesContent":["import * as createRoutePropertyOrder from './rules/create-route-property-order/create-route-property-order.rule'\nimport type { ESLintUtils } from '@typescript-eslint/utils'\nimport type { ExtraRuleDocs } from './types'\n\nexport const rules: Record<\n  string,\n  ESLintUtils.RuleModule<\n    string,\n    ReadonlyArray<unknown>,\n    ExtraRuleDocs,\n    ESLintUtils.RuleListener\n  >\n> = {\n  [createRoutePropertyOrder.name]: createRoutePropertyOrder.rule,\n}\n"],"names":["createRoutePropertyOrder.name","createRoutePropertyOrder.rule"],"mappings":";AAIO,MAAM,QAQT;AAAA,EACF,CAACA,IAA6B,GAAGC;AACnC;"}
+{"version":3,"file":"rules.js","sources":["../../src/rules.ts"],"sourcesContent":["import * as createRoutePropertyOrder from './rules/create-route-property-order/create-route-property-order.rule'\nimport * as routeParamNames from './rules/route-param-names/route-param-names.rule'\nimport type { ESLintUtils } from '@typescript-eslint/utils'\nimport type { ExtraRuleDocs } from './types'\n\nexport const rules: Record<\n  string,\n  ESLintUtils.RuleModule<\n    string,\n    ReadonlyArray<unknown>,\n    ExtraRuleDocs,\n    ESLintUtils.RuleListener\n  >\n> = {\n  [createRoutePropertyOrder.name]: createRoutePropertyOrder.rule,\n  [routeParamNames.name]: routeParamNames.rule,\n}\n"],"names":["createRoutePropertyOrder.name","createRoutePropertyOrder.rule","routeParamNames.name","routeParamNames.rule"],"mappings":";;AAKO,MAAM,QAQT;AAAA,EACF,CAACA,MAA6B,GAAGC;AAAAA,EACjC,CAACC,IAAoB,GAAGC;AAC1B;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/eslint-plugin-router",
-  "version": "1.141.0",
+  "version": "1.155.0",
   "description": "ESLint plugin for TanStack Router",
   "author": "Manuel Schiller",
   "license": "MIT",

package/src/__tests__/route-param-names.rule.test.ts

@@ -0,0 +1,271 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+
+import { name, rule } from '../rules/route-param-names/route-param-names.rule'
+
+const ruleTester = new RuleTester()
+
+ruleTester.run(name, rule, {
+  valid: [
+    // Valid param names - simple $param format
+    {
+      name: 'valid simple param: $userId',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$userId')({})
+      `,
+    },
+    {
+      name: 'valid simple param: $id',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/posts/$id')({})
+      `,
+    },
+    {
+      name: 'valid simple param: $_id (underscore prefix)',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/items/$_id')({})
+      `,
+    },
+    {
+      name: 'valid simple param: $$var (dollar prefix)',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/data/$$var')({})
+      `,
+    },
+    {
+      name: 'valid param with numbers: $user123',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$user123')({})
+      `,
+    },
+
+    // Valid param names - braces format {$param}
+    {
+      name: 'valid braces param: {$userName}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/{$userName}')({})
+      `,
+    },
+    {
+      name: 'valid braces param with prefix/suffix: prefix{$id}suffix',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/items/item-{$id}-details')({})
+      `,
+    },
+
+    // Valid optional params - {-$param}
+    {
+      name: 'valid optional param: {-$optional}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/search/{-$query}')({})
+      `,
+    },
+    {
+      name: 'valid optional param with prefix/suffix: prefix{-$opt}suffix',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/filter/by-{-$category}-items')({})
+      `,
+    },
+
+    // Wildcards - should be skipped (no validation)
+    {
+      name: 'wildcard: $ alone',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/files/$')({})
+      `,
+    },
+    {
+      name: 'wildcard: {$}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/catch/{$}')({})
+      `,
+    },
+
+    // Multiple valid params
+    {
+      name: 'multiple valid params in path',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$userId/posts/$postId')({})
+      `,
+    },
+
+    // createRoute with path property
+    {
+      name: 'createRoute with valid param in path property',
+      code: `
+        import { createRoute } from '@tanstack/react-router'
+        const Route = createRoute({ path: '/users/$userId' })
+      `,
+    },
+
+    // createLazyFileRoute
+    {
+      name: 'createLazyFileRoute with valid param',
+      code: `
+        import { createLazyFileRoute } from '@tanstack/react-router'
+        const Route = createLazyFileRoute('/users/$userId')({})
+      `,
+    },
+
+    // createLazyRoute
+    {
+      name: 'createLazyRoute with valid param',
+      code: `
+        import { createLazyRoute } from '@tanstack/react-router'
+        const Route = createLazyRoute('/users/$userId')({})
+      `,
+    },
+
+    // No params - should pass
+    {
+      name: 'no params in path',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/list')({})
+      `,
+    },
+
+    // Not from tanstack router - should be ignored
+    {
+      name: 'non-tanstack import should be ignored',
+      code: `
+        import { createFileRoute } from 'other-router'
+        const Route = createFileRoute('/users/$123invalid')({})
+      `,
+    },
+  ],
+
+  invalid: [
+    // Invalid param names - starts with number
+    {
+      name: 'invalid param starting with number: $123',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$123')({})
+      `,
+      errors: [{ messageId: 'invalidParamName', data: { paramName: '123' } }],
+    },
+    {
+      name: 'invalid param starting with number: $1user',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$1user')({})
+      `,
+      errors: [{ messageId: 'invalidParamName', data: { paramName: '1user' } }],
+    },
+
+    // Invalid param names - contains hyphen
+    {
+      name: 'invalid param with hyphen: $user-name',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$user-name')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: 'user-name' } },
+      ],
+    },
+
+    // Invalid param names - contains dot
+    {
+      name: 'invalid param with dot: {$my.param}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/{$my.param}')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: 'my.param' } },
+      ],
+    },
+
+    // Invalid param names - contains space
+    {
+      name: 'invalid param with space: {$param name}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/{$param name}')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: 'param name' } },
+      ],
+    },
+
+    // Invalid optional param
+    {
+      name: 'invalid optional param: {-$123invalid}',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/search/{-$123invalid}')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: '123invalid' } },
+      ],
+    },
+
+    // Multiple invalid params
+    {
+      name: 'multiple invalid params in path',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/users/$1id/posts/$post-id')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: '1id' } },
+        { messageId: 'invalidParamName', data: { paramName: 'post-id' } },
+      ],
+    },
+
+    // createRoute with invalid path property
+    {
+      name: 'createRoute with invalid param in path property',
+      code: `
+        import { createRoute } from '@tanstack/react-router'
+        const Route = createRoute({ path: '/users/$123' })
+      `,
+      errors: [{ messageId: 'invalidParamName', data: { paramName: '123' } }],
+    },
+
+    // createLazyFileRoute with invalid param
+    {
+      name: 'createLazyFileRoute with invalid param',
+      code: `
+        import { createLazyFileRoute } from '@tanstack/react-router'
+        const Route = createLazyFileRoute('/users/$user-id')({})
+      `,
+      errors: [
+        { messageId: 'invalidParamName', data: { paramName: 'user-id' } },
+      ],
+    },
+
+    // createLazyRoute with invalid param
+    {
+      name: 'createLazyRoute with invalid param',
+      code: `
+        import { createLazyRoute } from '@tanstack/react-router'
+        const Route = createLazyRoute('/users/$1abc')({})
+      `,
+      errors: [{ messageId: 'invalidParamName', data: { paramName: '1abc' } }],
+    },
+
+    // Invalid braces param with prefix/suffix
+    {
+      name: 'invalid braces param with prefix/suffix',
+      code: `
+        import { createFileRoute } from '@tanstack/react-router'
+        const Route = createFileRoute('/items/item-{$123}-details')({})
+      `,
+      errors: [{ messageId: 'invalidParamName', data: { paramName: '123' } }],
+    },
+  ],
+})

package/src/__tests__/route-param-names.utils.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest'
+import {
+  extractParamsFromPath,
+  extractParamsFromSegment,
+  getInvalidParams,
+  isValidParamName,
+} from '../rules/route-param-names/route-param-names.utils'
+
+describe('isValidParamName', () => {
+  it('should return true for valid param names', () => {
+    expect(isValidParamName('userId')).toBe(true)
+    expect(isValidParamName('id')).toBe(true)
+    expect(isValidParamName('_id')).toBe(true)
+    expect(isValidParamName('$var')).toBe(true)
+    expect(isValidParamName('user123')).toBe(true)
+    expect(isValidParamName('_')).toBe(true)
+    expect(isValidParamName('$')).toBe(true)
+    expect(isValidParamName('ABC')).toBe(true)
+    expect(isValidParamName('camelCase')).toBe(true)
+    expect(isValidParamName('PascalCase')).toBe(true)
+    expect(isValidParamName('snake_case')).toBe(true)
+    expect(isValidParamName('$$double')).toBe(true)
+    expect(isValidParamName('__double')).toBe(true)
+  })
+
+  it('should return false for invalid param names', () => {
+    expect(isValidParamName('123')).toBe(false)
+    expect(isValidParamName('1user')).toBe(false)
+    expect(isValidParamName('user-name')).toBe(false)
+    expect(isValidParamName('user.name')).toBe(false)
+    expect(isValidParamName('user name')).toBe(false)
+    expect(isValidParamName('')).toBe(false)
+    expect(isValidParamName('user@name')).toBe(false)
+    expect(isValidParamName('user#name')).toBe(false)
+    expect(isValidParamName('-user')).toBe(false)
+  })
+})
+
+describe('extractParamsFromSegment', () => {
+  it('should return empty array for segments without $', () => {
+    expect(extractParamsFromSegment('')).toEqual([])
+    expect(extractParamsFromSegment('users')).toEqual([])
+    expect(extractParamsFromSegment('static-segment')).toEqual([])
+  })
+
+  it('should skip wildcard segments', () => {
+    expect(extractParamsFromSegment('$')).toEqual([])
+    expect(extractParamsFromSegment('{$}')).toEqual([])
+  })
+
+  it('should extract simple $param format', () => {
+    const result = extractParamsFromSegment('$userId')
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({
+      fullParam: '$userId',
+      paramName: 'userId',
+      isOptional: false,
+      isValid: true,
+    })
+  })
+
+  it('should extract braces {$param} format', () => {
+    const result = extractParamsFromSegment('{$userId}')
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({
+      fullParam: '$userId',
+      paramName: 'userId',
+      isOptional: false,
+      isValid: true,
+    })
+  })
+
+  it('should extract braces with prefix/suffix', () => {
+    const result = extractParamsFromSegment('prefix{$id}suffix')
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({
+      fullParam: '$id',
+      paramName: 'id',
+      isOptional: false,
+      isValid: true,
+    })
+  })
+
+  it('should extract optional {-$param} format', () => {
+    const result = extractParamsFromSegment('{-$optional}')
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({
+      fullParam: '-$optional',
+      paramName: 'optional',
+      isOptional: true,
+      isValid: true,
+    })
+  })
+
+  it('should extract optional with prefix/suffix', () => {
+    const result = extractParamsFromSegment('pre{-$opt}post')
+    expect(result).toHaveLength(1)
+    expect(result[0]).toEqual({
+      fullParam: '-$opt',
+      paramName: 'opt',
+      isOptional: true,
+      isValid: true,
+    })
+  })
+
+  it('should mark invalid param names', () => {
+    const result = extractParamsFromSegment('$123invalid')
+    expect(result).toHaveLength(1)
+    expect(result[0]?.isValid).toBe(false)
+    expect(result[0]?.paramName).toBe('123invalid')
+  })
+
+  it('should mark hyphenated param names as invalid', () => {
+    const result = extractParamsFromSegment('$user-name')
+    expect(result).toHaveLength(1)
+    expect(result[0]?.isValid).toBe(false)
+    expect(result[0]?.paramName).toBe('user-name')
+  })
+})
+
+describe('extractParamsFromPath', () => {
+  it('should return empty array for paths without params', () => {
+    expect(extractParamsFromPath('')).toEqual([])
+    expect(extractParamsFromPath('/')).toEqual([])
+    expect(extractParamsFromPath('/users/list')).toEqual([])
+  })
+
+  it('should extract single param from path', () => {
+    const result = extractParamsFromPath('/users/$userId')
+    expect(result).toHaveLength(1)
+    expect(result[0]?.paramName).toBe('userId')
+  })
+
+  it('should extract multiple params from path', () => {
+    const result = extractParamsFromPath('/users/$userId/posts/$postId')
+    expect(result).toHaveLength(2)
+    expect(result[0]?.paramName).toBe('userId')
+    expect(result[1]?.paramName).toBe('postId')
+  })
+
+  it('should extract params with various formats', () => {
+    const result = extractParamsFromPath(
+      '/a/$simple/b/{$braces}/c/{-$optional}',
+    )
+    expect(result).toHaveLength(3)
+    expect(result[0]?.paramName).toBe('simple')
+    expect(result[0]?.isOptional).toBe(false)
+    expect(result[1]?.paramName).toBe('braces')
+    expect(result[1]?.isOptional).toBe(false)
+    expect(result[2]?.paramName).toBe('optional')
+    expect(result[2]?.isOptional).toBe(true)
+  })
+})
+
+describe('getInvalidParams', () => {
+  it('should return empty array for valid params', () => {
+    expect(getInvalidParams('/users/$userId')).toEqual([])
+    expect(getInvalidParams('/users/$_id')).toEqual([])
+    expect(getInvalidParams('/users/$$var')).toEqual([])
+  })
+
+  it('should return invalid params only', () => {
+    const result = getInvalidParams('/users/$123/posts/$validId')
+    expect(result).toHaveLength(1)
+    expect(result[0]?.paramName).toBe('123')
+  })
+
+  it('should return all invalid params', () => {
+    const result = getInvalidParams('/users/$1id/posts/$post-id')
+    expect(result).toHaveLength(2)
+    expect(result[0]?.paramName).toBe('1id')
+    expect(result[1]?.paramName).toBe('post-id')
+  })
+})

package/src/index.ts

@@ -26,6 +26,7 @@ Object.assign(plugin.configs, {
     plugins: ['@tanstack/eslint-plugin-router'],
     rules: {
       '@tanstack/router/create-route-property-order': 'warn',
+      '@tanstack/router/route-param-names': 'error',
     },
   },
   'flat/recommended': [
@@ -35,6 +36,7 @@ Object.assign(plugin.configs, {
       },
       rules: {
         '@tanstack/router/create-route-property-order': 'warn',
+        '@tanstack/router/route-param-names': 'error',
       },
     },
   ],

package/src/rules/route-param-names/constants.ts

@@ -0,0 +1,36 @@
+/**
+ * Functions where the path is passed as the first argument (string literal)
+ * e.g., createFileRoute('/path/$param')(...)
+ */
+export const pathAsFirstArgFunctions = [
+  'createFileRoute',
+  'createLazyFileRoute',
+  'createLazyRoute',
+] as const
+
+export type PathAsFirstArgFunction = (typeof pathAsFirstArgFunctions)[number]
+
+/**
+ * Functions where the path is a property in the options object
+ * e.g., createRoute({ path: '/path/$param' })
+ */
+export const pathAsPropertyFunctions = ['createRoute'] as const
+
+export type PathAsPropertyFunction = (typeof pathAsPropertyFunctions)[number]
+
+/**
+ * All route functions that need param name validation
+ */
+export const allRouteFunctions = [
+  ...pathAsFirstArgFunctions,
+  ...pathAsPropertyFunctions,
+] as const
+
+export type RouteFunction = (typeof allRouteFunctions)[number]
+
+/**
+ * Regex for valid JavaScript identifier (param name)
+ * Must start with letter, underscore, or dollar sign
+ * Can contain letters, numbers, underscores, or dollar signs
+ */
+export const VALID_PARAM_NAME_REGEX = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/

package/src/rules/route-param-names/route-param-names.rule.ts

@@ -0,0 +1,127 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackRouterImports } from '../../utils/detect-router-imports'
+import { getInvalidParams } from './route-param-names.utils'
+import { pathAsFirstArgFunctions, pathAsPropertyFunctions } from './constants'
+import type { TSESTree } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const pathAsFirstArgSet = new Set<string>(pathAsFirstArgFunctions)
+const pathAsPropertySet = new Set<string>(pathAsPropertyFunctions)
+
+export const name = 'route-param-names'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensure route param names are valid JavaScript identifiers',
+      recommended: 'error',
+    },
+    messages: {
+      invalidParamName:
+        'Invalid param name "{{paramName}}" in route path. Param names must be valid JavaScript identifiers (match /[a-zA-Z_$][a-zA-Z0-9_$]*/).',
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackRouterImports((context, _, helpers) => {
+    function reportInvalidParams(node: TSESTree.Node, path: string) {
+      const invalidParams = getInvalidParams(path)
+
+      for (const param of invalidParams) {
+        context.report({
+          node,
+          messageId: 'invalidParamName',
+          data: { paramName: param.paramName },
+        })
+      }
+    }
+
+    function getStringLiteralValue(node: TSESTree.Node): string | null {
+      if (
+        node.type === AST_NODE_TYPES.Literal &&
+        typeof node.value === 'string'
+      ) {
+        return node.value
+      }
+      if (
+        node.type === AST_NODE_TYPES.TemplateLiteral &&
+        node.quasis.length === 1
+      ) {
+        const cooked = node.quasis[0]?.value.cooked
+        if (cooked != null) {
+          return cooked
+        }
+      }
+      return null
+    }
+
+    return {
+      CallExpression(node) {
+        // Handle direct function call: createRoute({ path: '...' })
+        if (node.callee.type === AST_NODE_TYPES.Identifier) {
+          const funcName = node.callee.name
+
+          // Skip if not imported from TanStack Router
+          if (!helpers.isTanstackRouterImport(node.callee)) {
+            return
+          }
+
+          // Case: createRoute({ path: '/path/$param' }) or createRoute({ 'path': '/path/$param' })
+          if (pathAsPropertySet.has(funcName)) {
+            const arg = node.arguments[0]
+            if (arg?.type === AST_NODE_TYPES.ObjectExpression) {
+              for (const prop of arg.properties) {
+                if (prop.type === AST_NODE_TYPES.Property) {
+                  const isPathKey =
+                    (prop.key.type === AST_NODE_TYPES.Identifier &&
+                      prop.key.name === 'path') ||
+                    (prop.key.type === AST_NODE_TYPES.Literal &&
+                      prop.key.value === 'path')
+                  if (isPathKey) {
+                    const pathValue = getStringLiteralValue(prop.value)
+                    if (pathValue) {
+                      reportInvalidParams(prop.value, pathValue)
+                    }
+                  }
+                }
+              }
+            }
+            return
+          }
+        }
+
+        // Handle curried function call: createFileRoute('/path')({ ... })
+        if (node.callee.type === AST_NODE_TYPES.CallExpression) {
+          const innerCall = node.callee
+
+          if (innerCall.callee.type === AST_NODE_TYPES.Identifier) {
+            const funcName = innerCall.callee.name
+
+            // Skip if not imported from TanStack Router
+            if (!helpers.isTanstackRouterImport(innerCall.callee)) {
+              return
+            }
+
+            // Case: createFileRoute('/path/$param')(...) or similar
+            if (pathAsFirstArgSet.has(funcName)) {
+              const pathArg = innerCall.arguments[0]
+              if (pathArg) {
+                const pathValue = getStringLiteralValue(pathArg)
+                if (pathValue) {
+                  reportInvalidParams(pathArg, pathValue)
+                }
+              }
+            }
+          }
+        }
+      },
+    }
+  }),
+})