@tanstack/eslint-plugin-router 1.154.7 → 1.161.2

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

@@ -0,0 +1,61 @@
+import { VALID_PARAM_NAME_REGEX } from "./constants.js";
+function extractParamsFromSegment(segment) {
+  const params = [];
+  if (!segment || !segment.includes("$")) {
+    return params;
+  }
+  if (segment === "$" || segment === "{$}") {
+    return params;
+  }
+  if (segment.startsWith("$") && !segment.includes("{")) {
+    const paramName = segment.slice(1);
+    if (paramName) {
+      params.push({
+        fullParam: segment,
+        paramName,
+        isOptional: false,
+        isValid: VALID_PARAM_NAME_REGEX.test(paramName)
+      });
+    }
+    return params;
+  }
+  const bracePattern = /\{(-?\$)([^}]*)\}/g;
+  let match;
+  while ((match = bracePattern.exec(segment)) !== null) {
+    const prefix = match[1];
+    const paramName = match[2];
+    if (!paramName) {
+      continue;
+    }
+    const isOptional = prefix === "-$";
+    params.push({
+      fullParam: `${prefix}${paramName}`,
+      paramName,
+      isOptional,
+      isValid: VALID_PARAM_NAME_REGEX.test(paramName)
+    });
+  }
+  return params;
+}
+function extractParamsFromPath(path) {
+  if (!path || !path.includes("$")) {
+    return [];
+  }
+  const segments = path.split("/");
+  const allParams = [];
+  for (const segment of segments) {
+    const params = extractParamsFromSegment(segment);
+    allParams.push(...params);
+  }
+  return allParams;
+}
+function getInvalidParams(path) {
+  const params = extractParamsFromPath(path);
+  return params.filter((p) => !p.isValid);
+}
+export {
+  extractParamsFromPath,
+  extractParamsFromSegment,
+  getInvalidParams
+};
+//# sourceMappingURL=route-param-names.utils.js.map

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/dist/esm/utils/detect-router-imports.js

@@ -22,7 +22,8 @@ function detectTanstackRouterImports(create) {
     };
     const detectionInstructions = {
       ImportDeclaration(node) {
-        if (node.specifiers.length > 0 && node.importKind === "value" && node.source.value.startsWith("@tanstack/") && node.source.value.endsWith("-router")) {
+        if (node.specifiers.length > 0 && // `importKind` is parser-dependent and can be undefined (eg. Espree)
+        node.importKind !== "type" && node.source.value.startsWith("@tanstack/") && node.source.value.endsWith("-router")) {
           tanstackRouterImportSpecifiers.push(...node.specifiers);
         }
       }

package/dist/esm/utils/detect-router-imports.js.map

@@ -1 +1 @@
-{"version":3,"file":"detect-router-imports.js","sources":["../../../src/utils/detect-router-imports.ts"],"sourcesContent":["import { TSESTree } from '@typescript-eslint/utils'\nimport type { ESLintUtils, TSESLint } from '@typescript-eslint/utils'\n\ntype Create = Parameters<\n  ReturnType<typeof ESLintUtils.RuleCreator>\n>[0]['create']\n\ntype Context = Parameters<Create>[0]\ntype Options = Parameters<Create>[1]\ntype Helpers = {\n  isSpecificTanstackRouterImport: (\n    node: TSESTree.Identifier,\n    source: string,\n  ) => boolean\n  isTanstackRouterImport: (node: TSESTree.Identifier) => boolean\n}\n\ntype EnhancedCreate = (\n  context: Context,\n  options: Options,\n  helpers: Helpers,\n) => ReturnType<Create>\n\nexport function detectTanstackRouterImports(create: EnhancedCreate): Create {\n  return (context, optionsWithDefault) => {\n    const tanstackRouterImportSpecifiers: Array<TSESTree.ImportClause> = []\n\n    const helpers: Helpers = {\n      isSpecificTanstackRouterImport(node, source) {\n        return !!tanstackRouterImportSpecifiers.find((specifier) => {\n          if (\n            specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier &&\n            specifier.parent.type ===\n              TSESTree.AST_NODE_TYPES.ImportDeclaration &&\n            specifier.parent.source.value === source\n          ) {\n            return node.name === specifier.local.name\n          }\n\n          return false\n        })\n      },\n      isTanstackRouterImport(node) {\n        return !!tanstackRouterImportSpecifiers.find((specifier) => {\n          if (specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier) {\n            return node.name === specifier.local.name\n          }\n\n          return false\n        })\n      },\n    }\n\n    const detectionInstructions: TSESLint.RuleListener = {\n      ImportDeclaration(node) {\n        if (\n          node.specifiers.length > 0 &&\n          node.importKind === 'value' &&\n          node.source.value.startsWith('@tanstack/') &&\n          node.source.value.endsWith('-router')\n        ) {\n          tanstackRouterImportSpecifiers.push(...node.specifiers)\n        }\n      },\n    }\n\n    // Call original rule definition\n    const ruleInstructions = create(context, optionsWithDefault, helpers)\n    const enhancedRuleInstructions: TSESLint.RuleListener = {}\n\n    const allKeys = new Set(\n      Object.keys(detectionInstructions).concat(Object.keys(ruleInstructions)),\n    )\n\n    // Iterate over ALL instructions keys so we can override original rule instructions\n    // to prevent their execution if conditions to report errors are not met.\n    allKeys.forEach((instruction) => {\n      enhancedRuleInstructions[instruction] = (node) => {\n        if (instruction in detectionInstructions) {\n          detectionInstructions[instruction]?.(node)\n        }\n\n        const ruleFunction = ruleInstructions[instruction]\n        if (ruleFunction !== undefined) {\n          return ruleFunction(node)\n        }\n\n        return undefined\n      }\n    })\n\n    return enhancedRuleInstructions\n  }\n}\n"],"names":[],"mappings":";AAuBO,SAAS,4BAA4B,QAAgC;AAC1E,SAAO,CAAC,SAAS,uBAAuB;AACtC,UAAM,iCAA+D,CAAA;AAErE,UAAM,UAAmB;AAAA,MACvB,+BAA+B,MAAM,QAAQ;AAC3C,eAAO,CAAC,CAAC,+BAA+B,KAAK,CAAC,cAAc;AAC1D,cACE,UAAU,SAAS,SAAS,eAAe,mBAC3C,UAAU,OAAO,SACf,SAAS,eAAe,qBAC1B,UAAU,OAAO,OAAO,UAAU,QAClC;AACA,mBAAO,KAAK,SAAS,UAAU,MAAM;AAAA,UACvC;AAEA,iBAAO;AAAA,QACT,CAAC;AAAA,MACH;AAAA,MACA,uBAAuB,MAAM;AAC3B,eAAO,CAAC,CAAC,+BAA+B,KAAK,CAAC,cAAc;AAC1D,cAAI,UAAU,SAAS,SAAS,eAAe,iBAAiB;AAC9D,mBAAO,KAAK,SAAS,UAAU,MAAM;AAAA,UACvC;AAEA,iBAAO;AAAA,QACT,CAAC;AAAA,MACH;AAAA,IAAA;AAGF,UAAM,wBAA+C;AAAA,MACnD,kBAAkB,MAAM;AACtB,YACE,KAAK,WAAW,SAAS,KACzB,KAAK,eAAe,WACpB,KAAK,OAAO,MAAM,WAAW,YAAY,KACzC,KAAK,OAAO,MAAM,SAAS,SAAS,GACpC;AACA,yCAA+B,KAAK,GAAG,KAAK,UAAU;AAAA,QACxD;AAAA,MACF;AAAA,IAAA;AAIF,UAAM,mBAAmB,OAAO,SAAS,oBAAoB,OAAO;AACpE,UAAM,2BAAkD,CAAA;AAExD,UAAM,UAAU,IAAI;AAAA,MAClB,OAAO,KAAK,qBAAqB,EAAE,OAAO,OAAO,KAAK,gBAAgB,CAAC;AAAA,IAAA;AAKzE,YAAQ,QAAQ,CAAC,gBAAgB;AAC/B,+BAAyB,WAAW,IAAI,CAAC,SAAS;AAChD,YAAI,eAAe,uBAAuB;AACxC,gCAAsB,WAAW,IAAI,IAAI;AAAA,QAC3C;AAEA,cAAM,eAAe,iBAAiB,WAAW;AACjD,YAAI,iBAAiB,QAAW;AAC9B,iBAAO,aAAa,IAAI;AAAA,QAC1B;AAEA,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT;AACF;"}
+{"version":3,"file":"detect-router-imports.js","sources":["../../../src/utils/detect-router-imports.ts"],"sourcesContent":["import { TSESTree } from '@typescript-eslint/utils'\nimport type { ESLintUtils, TSESLint } from '@typescript-eslint/utils'\n\ntype Create = Parameters<\n  ReturnType<typeof ESLintUtils.RuleCreator>\n>[0]['create']\n\ntype Context = Parameters<Create>[0]\ntype Options = Parameters<Create>[1]\ntype Helpers = {\n  isSpecificTanstackRouterImport: (\n    node: TSESTree.Identifier,\n    source: string,\n  ) => boolean\n  isTanstackRouterImport: (node: TSESTree.Identifier) => boolean\n}\n\ntype EnhancedCreate = (\n  context: Context,\n  options: Options,\n  helpers: Helpers,\n) => ReturnType<Create>\n\nexport function detectTanstackRouterImports(create: EnhancedCreate): Create {\n  return (context, optionsWithDefault) => {\n    const tanstackRouterImportSpecifiers: Array<TSESTree.ImportClause> = []\n\n    const helpers: Helpers = {\n      isSpecificTanstackRouterImport(node, source) {\n        return !!tanstackRouterImportSpecifiers.find((specifier) => {\n          if (\n            specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier &&\n            specifier.parent.type ===\n              TSESTree.AST_NODE_TYPES.ImportDeclaration &&\n            specifier.parent.source.value === source\n          ) {\n            return node.name === specifier.local.name\n          }\n\n          return false\n        })\n      },\n      isTanstackRouterImport(node) {\n        return !!tanstackRouterImportSpecifiers.find((specifier) => {\n          if (specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier) {\n            return node.name === specifier.local.name\n          }\n\n          return false\n        })\n      },\n    }\n\n    const detectionInstructions: TSESLint.RuleListener = {\n      ImportDeclaration(node) {\n        if (\n          node.specifiers.length > 0 &&\n          // `importKind` is parser-dependent and can be undefined (eg. Espree)\n          node.importKind !== 'type' &&\n          node.source.value.startsWith('@tanstack/') &&\n          node.source.value.endsWith('-router')\n        ) {\n          tanstackRouterImportSpecifiers.push(...node.specifiers)\n        }\n      },\n    }\n\n    // Call original rule definition\n    const ruleInstructions = create(context, optionsWithDefault, helpers)\n    const enhancedRuleInstructions: TSESLint.RuleListener = {}\n\n    const allKeys = new Set(\n      Object.keys(detectionInstructions).concat(Object.keys(ruleInstructions)),\n    )\n\n    // Iterate over ALL instructions keys so we can override original rule instructions\n    // to prevent their execution if conditions to report errors are not met.\n    allKeys.forEach((instruction) => {\n      enhancedRuleInstructions[instruction] = (node) => {\n        if (instruction in detectionInstructions) {\n          detectionInstructions[instruction]?.(node)\n        }\n\n        const ruleFunction = ruleInstructions[instruction]\n        if (ruleFunction !== undefined) {\n          return ruleFunction(node)\n        }\n\n        return undefined\n      }\n    })\n\n    return enhancedRuleInstructions\n  }\n}\n"],"names":[],"mappings":";AAuBO,SAAS,4BAA4B,QAAgC;AAC1E,SAAO,CAAC,SAAS,uBAAuB;AACtC,UAAM,iCAA+D,CAAA;AAErE,UAAM,UAAmB;AAAA,MACvB,+BAA+B,MAAM,QAAQ;AAC3C,eAAO,CAAC,CAAC,+BAA+B,KAAK,CAAC,cAAc;AAC1D,cACE,UAAU,SAAS,SAAS,eAAe,mBAC3C,UAAU,OAAO,SACf,SAAS,eAAe,qBAC1B,UAAU,OAAO,OAAO,UAAU,QAClC;AACA,mBAAO,KAAK,SAAS,UAAU,MAAM;AAAA,UACvC;AAEA,iBAAO;AAAA,QACT,CAAC;AAAA,MACH;AAAA,MACA,uBAAuB,MAAM;AAC3B,eAAO,CAAC,CAAC,+BAA+B,KAAK,CAAC,cAAc;AAC1D,cAAI,UAAU,SAAS,SAAS,eAAe,iBAAiB;AAC9D,mBAAO,KAAK,SAAS,UAAU,MAAM;AAAA,UACvC;AAEA,iBAAO;AAAA,QACT,CAAC;AAAA,MACH;AAAA,IAAA;AAGF,UAAM,wBAA+C;AAAA,MACnD,kBAAkB,MAAM;AACtB,YACE,KAAK,WAAW,SAAS;AAAA,QAEzB,KAAK,eAAe,UACpB,KAAK,OAAO,MAAM,WAAW,YAAY,KACzC,KAAK,OAAO,MAAM,SAAS,SAAS,GACpC;AACA,yCAA+B,KAAK,GAAG,KAAK,UAAU;AAAA,QACxD;AAAA,MACF;AAAA,IAAA;AAIF,UAAM,mBAAmB,OAAO,SAAS,oBAAoB,OAAO;AACpE,UAAM,2BAAkD,CAAA;AAExD,UAAM,UAAU,IAAI;AAAA,MAClB,OAAO,KAAK,qBAAqB,EAAE,OAAO,OAAO,KAAK,gBAAgB,CAAC;AAAA,IAAA;AAKzE,YAAQ,QAAQ,CAAC,gBAAgB;AAC/B,+BAAyB,WAAW,IAAI,CAAC,SAAS;AAChD,YAAI,eAAe,uBAAuB;AACxC,gCAAsB,WAAW,IAAI,IAAI;AAAA,QAC3C;AAEA,cAAM,eAAe,iBAAiB,WAAW;AACjD,YAAI,iBAAiB,QAAW;AAC9B,iBAAO,aAAa,IAAI;AAAA,QAC1B;AAEA,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/eslint-plugin-router",
-  "version": "1.154.7",
+  "version": "1.161.2",
   "description": "ESLint plugin for TanStack Router",
   "author": "Manuel Schiller",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "eslint": "^9.22.0"
   },
   "peerDependencies": {
-    "eslint": "^8.57.0 || ^9.0.0"
+    "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0"
   },
   "scripts": {
     "clean": "rimraf ./dist ./coverage",

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_$]*$/