fix: Fix literal underscore paths under pathless layouts (#7408)

Author: schiller-manuel

.changeset/quiet-ravens-explain.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/router-generator': patch
+---
+
+Fix literal underscore route paths when they are nested under pathless layouts. Virtual `route()` paths now treat leading and trailing underscores as literal URL path characters, while physical file routes continue to use bracket escapes for literal underscore segments.

docs/router/routing/virtual-file-routes.md

@@ -187,6 +187,8 @@ export const routes = rootRoute('root.tsx', [
 ])
 ```
 
+Because `route` receives an explicit URL path, leading and trailing underscores are treated literally. Use `layout` to create pathless layout routes.
+
 You can also define a virtual route without a file name. This allows to set a common path prefix for its children:
 
 ```tsx

packages/router-generator/src/filesystem/physical/getRouteNodes.ts

@@ -2,9 +2,11 @@ import path from 'node:path'
 import * as fsp from 'node:fs/promises'
 import {
   cleanPath,
+  createRoutePathSegmentMetadata,
   determineInitialRoutePath,
   escapeRegExp,
   hasEscapedLeadingUnderscore,
+  joinRoutePathSegmentMetadata,
   removeExt,
   replaceBackslash,
   routePathToVariable,
@@ -126,11 +128,18 @@ export async function getRouteNodes(
         const filePath = replaceBackslash(
           path.join(normalizedDir, node.filePath),
         )
+        const prefixPath = cleanPath(`/${normalizedDir}`)
         const routePath = cleanPath(`/${normalizedDir}${node.routePath}`)
 
         node.variableName = routePathToVariable(
           cleanPath(`/${normalizedDir}/${removeExt(node.filePath)}`),
         )
+        node._routePathSegmentMetadata = joinRoutePathSegmentMetadata(
+          routePath,
+          prefixPath,
+          undefined,
+          node._routePathSegmentMetadata,
+        )
         node.routePath = routePath
         // Keep originalRoutePath aligned with routePath for escape detection
         if (node.originalRoutePath) {
@@ -334,6 +343,10 @@ export async function getRouteNodes(
             variableName,
             _fsRouteType: routeType,
             originalRoutePath,
+            _routePathSegmentMetadata: createRoutePathSegmentMetadata(
+              routePath,
+              originalRoutePath,
+            ),
           })
         }
       }),

packages/router-generator/src/filesystem/virtual/getRouteNodes.ts

@@ -1,7 +1,10 @@
 import path, { join, resolve } from 'node:path'
 import {
   cleanPath,
+  createLiteralRoutePathSegmentMetadata,
+  createRoutePathSegmentMetadata,
   determineInitialRoutePath,
+  joinRoutePathSegmentMetadata,
   removeExt,
   removeLeadingSlash,
   removeTrailingSlash,
@@ -162,16 +165,26 @@ export async function getRouteNodesRecursive(
           ...physicalDirectories,
         )
         routeNodes.forEach((subtreeNode) => {
+          const pathPrefix = cleanPath(
+            `${parent?.routePath ?? ''}${node.pathPrefix}`,
+          )
+          const literalPathPrefixSegments =
+            createLiteralRoutePathSegmentMetadata(pathPrefix, parent, true)
+          const routePath = cleanPath(`${pathPrefix}${subtreeNode.routePath}`)
           subtreeNode.variableName = routePathToVariable(
             `${node.pathPrefix}/${removeExt(subtreeNode.filePath)}`,
           )
-          subtreeNode.routePath = cleanPath(
-            `${parent?.routePath ?? ''}${node.pathPrefix}${subtreeNode.routePath}`,
+          subtreeNode._routePathSegmentMetadata = joinRoutePathSegmentMetadata(
+            routePath,
+            pathPrefix,
+            literalPathPrefixSegments,
+            subtreeNode._routePathSegmentMetadata,
           )
+          subtreeNode.routePath = routePath
           // Keep originalRoutePath aligned with routePath for escape detection
           if (subtreeNode.originalRoutePath) {
             subtreeNode.originalRoutePath = cleanPath(
-              `${parent?.routePath ?? ''}${node.pathPrefix}${subtreeNode.originalRoutePath}`,
+              `${parent?.originalRoutePath ?? parent?.routePath ?? ''}${node.pathPrefix}${subtreeNode.originalRoutePath}`,
             )
           }
           subtreeNode.filePath = `${node.directory}/${subtreeNode.filePath}`
@@ -186,6 +199,9 @@ export async function getRouteNodesRecursive(
         return { filePath, variableName, fullPath }
       }
       const parentRoutePath = removeTrailingSlash(parent?.routePath ?? '/')
+      const parentOriginalRoutePath = removeTrailingSlash(
+        parent?.originalRoutePath ?? parent?.routePath ?? '/',
+      )
       const virtualParentRoutePath = parent?.routePath ?? `/${rootPathId}`
 
       switch (node.type) {
@@ -212,8 +228,9 @@ export async function getRouteNodesRecursive(
             originalRoutePath: originalSegment,
           } = determineInitialRoutePath(removeLeadingSlash(lastSegment))
           const routePath = `${parentRoutePath}${escapedSegment}`
-          // Store the original path with brackets for escape detection
-          const originalRoutePath = `${parentRoutePath}${originalSegment}`
+          const originalRoutePath = `${parentOriginalRoutePath}${originalSegment}`
+          const routePathSegmentMetadata =
+            createLiteralRoutePathSegmentMetadata(routePath, parent, true)
 
           if (node.file) {
             const { filePath, variableName, fullPath } = getFile(node.file)
@@ -223,6 +240,7 @@ export async function getRouteNodesRecursive(
               variableName,
               routePath,
               originalRoutePath,
+              _routePathSegmentMetadata: routePathSegmentMetadata,
               _fsRouteType: 'static',
               _virtualParentRoutePath: virtualParentRoutePath,
             }
@@ -233,6 +251,7 @@ export async function getRouteNodesRecursive(
               variableName: routePathToVariable(routePath),
               routePath,
               originalRoutePath,
+              _routePathSegmentMetadata: routePathSegmentMetadata,
               isVirtual: true,
               _fsRouteType: 'static',
               _virtualParentRoutePath: virtualParentRoutePath,
@@ -275,14 +294,21 @@ export async function getRouteNodesRecursive(
           } = determineInitialRoutePath(removeLeadingSlash(lastSegment))
           const routePath = `${parentRoutePath}${escapedSegment}`
           // Store the original path with brackets for escape detection
-          const originalRoutePath = `${parentRoutePath}${originalSegment}`
+          const originalRoutePath = `${parentOriginalRoutePath}${originalSegment}`
+          const routePathSegmentMetadata = joinRoutePathSegmentMetadata(
+            routePath,
+            parentRoutePath,
+            parent?._routePathSegmentMetadata,
+            createRoutePathSegmentMetadata(escapedSegment, originalSegment),
+          )
 
           const routeNode: RouteNode = {
             fullPath,
             filePath,
             variableName,
             routePath,
             originalRoutePath,
+            _routePathSegmentMetadata: routePathSegmentMetadata,
             _fsRouteType: 'pathless_layout',
             _virtualParentRoutePath: virtualParentRoutePath,
           }

packages/router-generator/src/generator.ts

@@ -17,6 +17,8 @@ import {
   buildRouteTreeConfig,
   checkFileExists,
   checkRouteFullPathUniqueness,
+  countRoutePathSegments,
+  countSlashSeparatedParts,
   createRouteNodesByFullPath,
   createRouteNodesById,
   createRouteNodesByTo,
@@ -33,9 +35,8 @@ import {
   removeExt,
   removeGroups,
   removeLastSegmentFromPath,
-  removeLayoutSegmentsWithEscape,
+  removeLayoutSegmentsAndUnderscoresWithEscape,
   removeTrailingSlash,
-  removeUnderscoresWithEscape,
   replaceBackslash,
   trimPathLeft,
 } from './utils'
@@ -51,6 +52,7 @@ import type {
   HandleNodeAccumulator,
   ImportDeclaration,
   RouteNode,
+  RoutePathSegmentMetadata,
 } from './types'
 import type { Config } from './config'
 import type { Logger } from './logger'
@@ -70,6 +72,32 @@ interface fs {
   chown: (filePath: string, uid: number, gid: number) => Promise<void>
 }
 
+function getRoutePathSegmentMetadataForPath(
+  node: RouteNode,
+  routePath: string,
+  parentRoutePath?: string,
+): Array<RoutePathSegmentMetadata | undefined> | undefined {
+  if (!node._routePathSegmentMetadata) return undefined
+
+  const segments = routePath.split('/')
+  const result = new Array<RoutePathSegmentMetadata | undefined>(
+    segments.length,
+  )
+  const parentSegmentCount = countRoutePathSegments(parentRoutePath)
+  let hasMetadata = false
+  let segmentCount = 0
+
+  for (let i = 0; i < segments.length; i++) {
+    if (!segments[i]) continue
+    const sourceIndex = parentSegmentCount + segmentCount + 1
+    result[i] = node._routePathSegmentMetadata[sourceIndex]
+    hasMetadata ||= !!result[i]
+    segmentCount++
+  }
+
+  return hasMetadata ? result : undefined
+}
+
 const DefaultFileSystem: fs = {
   stat: async (filePath) => {
     const res = await fsp.stat(filePath, { bigint: true })
@@ -392,7 +420,10 @@ export class Generator {
 
     const preRouteNodes = multiSortBy(beforeRouteNodes, [
       (d) => (d.routePath === '/' ? -1 : 1),
-      (d) => d.routePath?.split('/').length,
+      (d) =>
+        d.routePath === undefined
+          ? undefined
+          : countSlashSeparatedParts(d.routePath),
       (d) => (d.filePath.match(this.indexTokenFilenameRegex) ? 1 : -1),
       (d) => (d.filePath.match(Generator.componentPieceRegex) ? 1 : -1),
       (d) => (d.filePath.match(this.routeTokenFilenameRegex) ? -1 : 1),
@@ -587,7 +618,10 @@ export class Generator {
 
     const sortedRouteNodes = multiSortBy(acc.routeNodes, [
       (d) => (d.routePath?.includes(`/${rootPathId}`) ? -1 : 1),
-      (d) => d.routePath?.split('/').length,
+      (d) =>
+        d.routePath === undefined
+          ? undefined
+          : countSlashSeparatedParts(d.routePath),
       (d) => {
         const segments = d.routePath?.split('/').filter(Boolean) ?? []
         const last = segments[segments.length - 1] ?? ''
@@ -1430,29 +1464,39 @@ ${acc.routeTree.map((child) => `${child.variableName}Route: typeof ${getResolved
     node.path = determineNodePath(node)
 
     const trimmedPath = trimPathLeft(node.path ?? '')
-    const trimmedOriginalPath = trimPathLeft(
-      node.originalRoutePath?.replace(
-        node.parent?.originalRoutePath ?? '',
-        '',
-      ) ?? '',
+    const originalPath =
+      node.originalRoutePath && node.parent?.originalRoutePath
+        ? node.originalRoutePath.replace(node.parent.originalRoutePath, '') ||
+          '/'
+        : node.originalRoutePath
+    const routePathSegmentMetadata = getRoutePathSegmentMetadataForPath(
+      node,
+      node.path ?? '/',
+      node.parent?.routePath,
     )
+    const trimmedOriginalPath = trimPathLeft(originalPath ?? '')
 
     const split = trimmedPath.split('/')
+    const pathSplit = (node.path ?? '').split('/')
     const originalSplit = trimmedOriginalPath.split('/')
     const lastRouteSegment = split[split.length - 1] ?? trimmedPath
     const lastOriginalSegment =
       originalSplit[originalSplit.length - 1] ?? trimmedOriginalPath
+    const lastRouteSegmentMetadata =
+      routePathSegmentMetadata?.[pathSplit.length - 1]
 
     // A segment is non-path if it starts with underscore AND the underscore is not escaped
     node.isNonPath =
-      isSegmentPathless(lastRouteSegment, lastOriginalSegment) ||
+      (!lastRouteSegmentMetadata?.literalLeadingUnderscore &&
+        isSegmentPathless(lastRouteSegment, lastOriginalSegment)) ||
       split.every((part) => this.routeGroupPatternRegex.test(part))
 
-    // Use escape-aware functions to compute cleanedPath
+    // Use a single pass so layout removal does not desync escaped underscore checks.
     node.cleanedPath = removeGroups(
-      removeUnderscoresWithEscape(
-        removeLayoutSegmentsWithEscape(node.path, node.originalRoutePath),
-        node.originalRoutePath,
+      removeLayoutSegmentsAndUnderscoresWithEscape(
+        node.path,
+        originalPath,
+        routePathSegmentMetadata,
       ),
     )
 
@@ -1530,13 +1574,17 @@ ${acc.routeTree.map((child) => `${child.variableName}Route: typeof ${getResolved
               candidate.originalRoutePath ?? '',
               '',
             ) || '/'
+          const routePathSegmentMetadataRelativeToParent =
+            getRoutePathSegmentMetadataForPath(
+              node,
+              pathRelativeToParent,
+              candidate.routePath,
+            )
           node.cleanedPath = removeGroups(
-            removeUnderscoresWithEscape(
-              removeLayoutSegmentsWithEscape(
-                pathRelativeToParent,
-                originalPathRelativeToParent,
-              ),
+            removeLayoutSegmentsAndUnderscoresWithEscape(
+              pathRelativeToParent,
               originalPathRelativeToParent,
+              routePathSegmentMetadataRelativeToParent,
             ),
           )
           break

packages/router-generator/src/types.ts

@@ -1,3 +1,8 @@
+export type RoutePathSegmentMetadata = {
+  literalLeadingUnderscore?: boolean
+  literalTrailingUnderscore?: boolean
+}
+
 export type RouteNode = {
   filePath: string
   fullPath: string
@@ -20,6 +25,8 @@ export type RouteNode = {
    * (e.g., when the parent is a virtual file-less route that gets filtered out).
    */
   _virtualParentRoutePath?: string
+  /** Internal routePath segment metadata for escaped or explicit literal syntax. */
+  _routePathSegmentMetadata?: Array<RoutePathSegmentMetadata | undefined>
 }
 
 export interface GetRouteNodesResult {