fix(router-generator): make buildRouteTree route ordering deterministic

.changeset/deterministic-route-tree-sort.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/router-generator": patch
+---
+
+Make `buildRouteTree` route ordering deterministic. Its final sort tiebreaker compared whole route-node objects (`(d) => d`), which coerce to `"[object Object]"` and so never order — an inconsistent comparator that left routes tying on segment-count/index-token in an engine- and input-dependent order, producing non-deterministic `routeTree.gen.ts` diffs across machines. The tiebreaker now compares `routePath`, mirroring the pre-sort and giving a stable total order.

packages/router-generator/src/generator.ts

@@ -38,6 +38,7 @@ import {
   removeLayoutSegmentsAndUnderscoresWithEscape,
   removeTrailingSlash,
   replaceBackslash,
+  sortRouteNodes,
   trimPathLeft,
 } from './utils'
 import { fillTemplate, getTargetTemplate } from './template'
@@ -616,19 +617,10 @@ export class Generator {
         ? this.indexTokenSegmentRegex
         : createTokenRegex(config.indexToken, { type: 'segment' })
 
-    const sortedRouteNodes = multiSortBy(acc.routeNodes, [
-      (d) => (d.routePath?.includes(`/${rootPathId}`) ? -1 : 1),
-      (d) =>
-        d.routePath === undefined
-          ? undefined
-          : countSlashSeparatedParts(d.routePath),
-      (d) => {
-        const segments = d.routePath?.split('/').filter(Boolean) ?? []
-        const last = segments[segments.length - 1] ?? ''
-        return indexTokenSegmentRegex.test(last) ? -1 : 1
-      },
-      (d) => d,
-    ])
+    const sortedRouteNodes = sortRouteNodes(
+      acc.routeNodes,
+      indexTokenSegmentRegex,
+    )
 
     const routeImports: Array<ImportDeclaration> = []
     const virtualRouteNodes: Array<string> = []

packages/router-generator/src/index.ts

@@ -23,6 +23,7 @@ export {
   removeUnderscores,
   resetRegex,
   multiSortBy,
+  sortRouteNodes,
   writeIfDifferent,
   format,
   removeExt,

packages/router-generator/src/utils.ts

@@ -123,6 +123,38 @@ export function multiSortBy<T>(
   return result
 }
 
+/**
+ * Sorts route nodes into the deterministic order used when generating the route
+ * tree. Precedence: root (`__root`) first, then by slash-separated segment
+ * count, then index segments before non-index, and finally — the tiebreaker —
+ * by `routePath`.
+ *
+ * The `routePath` tiebreaker is load-bearing: `routePath` is unique per node, so
+ * it gives the comparator a total order. Without it (e.g. comparing whole route
+ * nodes), any nodes tying on every earlier key are left in an engine- and
+ * input-order-dependent order by `Array.prototype.sort`, which makes the
+ * generated route tree churn non-deterministically across machines and Node
+ * versions.
+ */
+export function sortRouteNodes(
+  routeNodes: Array<RouteNode>,
+  indexTokenSegmentRegex: RegExp,
+): Array<RouteNode> {
+  return multiSortBy(routeNodes, [
+    (d) => (d.routePath?.includes(`/${rootPathId}`) ? -1 : 1),
+    (d) =>
+      d.routePath === undefined
+        ? undefined
+        : countSlashSeparatedParts(d.routePath),
+    (d) => {
+      const segments = d.routePath?.split('/').filter(Boolean) ?? []
+      const last = segments[segments.length - 1] ?? ''
+      return indexTokenSegmentRegex.test(last) ? -1 : 1
+    },
+    (d) => d.routePath,
+  ])
+}
+
 export function cleanPath(path: string) {
   // remove double slashes
   return path.replace(/\/{2,}/g, '/')

packages/router-generator/tests/generator/add-extensions-custom/routeTree.snapshot.ts

@@ -9,19 +9,19 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root.js'
-import { Route as PostsRouteImport } from './routes/posts.js'
 import { Route as IndexRouteImport } from './routes/index.js'
+import { Route as PostsRouteImport } from './routes/posts.js'
 
-const PostsRoute = PostsRouteImport.update({
-  id: '/posts',
-  path: '/posts',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const PostsRoute = PostsRouteImport.update({
+  id: '/posts',
+  path: '/posts',
+  getParentRoute: () => rootRouteImport,
+} as any)
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
@@ -51,20 +51,20 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/posts': {
-      id: '/posts'
-      path: '/posts'
-      fullPath: '/posts'
-      preLoaderRoute: typeof PostsRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/': {
       id: '/'
       path: '/'
       fullPath: '/'
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/posts': {
+      id: '/posts'
+      path: '/posts'
+      fullPath: '/posts'
+      preLoaderRoute: typeof PostsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
   }
 }
 

packages/router-generator/tests/generator/custom-scaffolding/routeTree.snapshot.ts

@@ -16,16 +16,16 @@ import { Route as ApiBarRouteImport } from './routes/api/bar'
 
 const FooLazyRouteImport = createFileRoute('/foo')()
 
-const FooLazyRoute = FooLazyRouteImport.update({
-  id: '/foo',
-  path: '/foo',
-  getParentRoute: () => rootRouteImport,
-} as any).lazy(() => import('./routes/foo.lazy').then((d) => d.Route))
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
+const FooLazyRoute = FooLazyRouteImport.update({
+  id: '/foo',
+  path: '/foo',
+  getParentRoute: () => rootRouteImport,
+} as any).lazy(() => import('./routes/foo.lazy').then((d) => d.Route))
 const ApiBarRoute = ApiBarRouteImport.update({
   id: '/api/bar',
   path: '/api/bar',
@@ -64,20 +64,20 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/foo': {
-      id: '/foo'
-      path: '/foo'
-      fullPath: '/foo'
-      preLoaderRoute: typeof FooLazyRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/': {
       id: '/'
       path: '/'
       fullPath: '/'
       preLoaderRoute: typeof IndexRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/foo': {
+      id: '/foo'
+      path: '/foo'
+      fullPath: '/foo'
+      preLoaderRoute: typeof FooLazyRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/bar': {
       id: '/api/bar'
       path: '/api/bar'

packages/router-generator/tests/generator/custom-tokens/routeTree.snapshot.ts

@@ -9,35 +9,30 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
-import { Route as PostsR0ut3RouteImport } from './routes/posts/_r0ut3_'
-import { Route as BlogR0ut3RouteImport } from './routes/blog/_r0ut3_'
 import { Route as R1nd3xRouteImport } from './routes/_1nd3x'
-import { Route as Posts1nd3xRouteImport } from './routes/posts/_1nd3x'
+import { Route as BlogR0ut3RouteImport } from './routes/blog/_r0ut3_'
+import { Route as PostsR0ut3RouteImport } from './routes/posts/_r0ut3_'
 import { Route as Blog1nd3xRouteImport } from './routes/blog/_1nd3x'
 import { Route as BlogSlugRouteImport } from './routes/blog/$slug'
+import { Route as Posts1nd3xRouteImport } from './routes/posts/_1nd3x'
 import { Route as PostsPostId1nd3xRouteImport } from './routes/posts/$postId/_1nd3x'
 import { Route as PostsPostIdDeepRouteImport } from './routes/posts/$postId/deep'
 
-const PostsR0ut3Route = PostsR0ut3RouteImport.update({
-  id: '/posts',
-  path: '/posts',
+const R1nd3xRoute = R1nd3xRouteImport.update({
+  id: '/',
+  path: '/',
   getParentRoute: () => rootRouteImport,
 } as any)
 const BlogR0ut3Route = BlogR0ut3RouteImport.update({
   id: '/blog',
   path: '/blog',
   getParentRoute: () => rootRouteImport,
 } as any)
-const R1nd3xRoute = R1nd3xRouteImport.update({
-  id: '/',
-  path: '/',
+const PostsR0ut3Route = PostsR0ut3RouteImport.update({
+  id: '/posts',
+  path: '/posts',
   getParentRoute: () => rootRouteImport,
 } as any)
-const Posts1nd3xRoute = Posts1nd3xRouteImport.update({
-  id: '/',
-  path: '/',
-  getParentRoute: () => PostsR0ut3Route,
-} as any)
 const Blog1nd3xRoute = Blog1nd3xRouteImport.update({
   id: '/',
   path: '/',
@@ -48,6 +43,11 @@ const BlogSlugRoute = BlogSlugRouteImport.update({
   path: '/$slug',
   getParentRoute: () => BlogR0ut3Route,
 } as any)
+const Posts1nd3xRoute = Posts1nd3xRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => PostsR0ut3Route,
+} as any)
 const PostsPostId1nd3xRoute = PostsPostId1nd3xRouteImport.update({
   id: '/$postId/',
   path: '/$postId/',
@@ -127,11 +127,11 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/posts': {
-      id: '/posts'
-      path: '/posts'
-      fullPath: '/posts'
-      preLoaderRoute: typeof PostsR0ut3RouteImport
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof R1nd3xRouteImport
       parentRoute: typeof rootRouteImport
     }
     '/blog': {
@@ -141,20 +141,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof BlogR0ut3RouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/': {
-      id: '/'
-      path: '/'
-      fullPath: '/'
-      preLoaderRoute: typeof R1nd3xRouteImport
+    '/posts': {
+      id: '/posts'
+      path: '/posts'
+      fullPath: '/posts'
+      preLoaderRoute: typeof PostsR0ut3RouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/posts/': {
-      id: '/posts/'
-      path: '/'
-      fullPath: '/posts/'
-      preLoaderRoute: typeof Posts1nd3xRouteImport
-      parentRoute: typeof PostsR0ut3Route
-    }
     '/blog/': {
       id: '/blog/'
       path: '/'
@@ -169,6 +162,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof BlogSlugRouteImport
       parentRoute: typeof BlogR0ut3Route
     }
+    '/posts/': {
+      id: '/posts/'
+      path: '/'
+      fullPath: '/posts/'
+      preLoaderRoute: typeof Posts1nd3xRouteImport
+      parentRoute: typeof PostsR0ut3Route
+    }
     '/posts/$postId/': {
       id: '/posts/$postId/'
       path: '/$postId'

packages/router-generator/tests/generator/dot-escaped/routeTree.snapshot.ts

@@ -9,32 +9,32 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
-import { Route as ScriptDotjsRouteImport } from './routes/script[.]js'
 import { Route as NestedDotjsRouteImport } from './routes/nested[.]js'
-import { Route as NestedDotjsScriptDotjsRouteImport } from './routes/nested[.]js.script[.]js'
+import { Route as ScriptDotjsRouteImport } from './routes/script[.]js'
 import { Route as NestedDotjsDoubleDotextDotjsRouteImport } from './routes/nested[.]js.double[.]ext[.]js'
+import { Route as NestedDotjsScriptDotjsRouteImport } from './routes/nested[.]js.script[.]js'
 
-const ScriptDotjsRoute = ScriptDotjsRouteImport.update({
-  id: '/script.js',
-  path: '/script.js',
-  getParentRoute: () => rootRouteImport,
-} as any)
 const NestedDotjsRoute = NestedDotjsRouteImport.update({
   id: '/nested.js',
   path: '/nested.js',
   getParentRoute: () => rootRouteImport,
 } as any)
-const NestedDotjsScriptDotjsRoute = NestedDotjsScriptDotjsRouteImport.update({
+const ScriptDotjsRoute = ScriptDotjsRouteImport.update({
   id: '/script.js',
   path: '/script.js',
-  getParentRoute: () => NestedDotjsRoute,
+  getParentRoute: () => rootRouteImport,
 } as any)
 const NestedDotjsDoubleDotextDotjsRoute =
   NestedDotjsDoubleDotextDotjsRouteImport.update({
     id: '/double.ext.js',
     path: '/double.ext.js',
     getParentRoute: () => NestedDotjsRoute,
   } as any)
+const NestedDotjsScriptDotjsRoute = NestedDotjsScriptDotjsRouteImport.update({
+  id: '/script.js',
+  path: '/script.js',
+  getParentRoute: () => NestedDotjsRoute,
+} as any)
 
 export interface FileRoutesByFullPath {
   '/nested.js': typeof NestedDotjsRouteWithChildren
@@ -83,26 +83,19 @@ export interface RootRouteChildren {
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
-    '/script.js': {
-      id: '/script.js'
-      path: '/script.js'
-      fullPath: '/script.js'
-      preLoaderRoute: typeof ScriptDotjsRouteImport
-      parentRoute: typeof rootRouteImport
-    }
     '/nested.js': {
       id: '/nested.js'
       path: '/nested.js'
       fullPath: '/nested.js'
       preLoaderRoute: typeof NestedDotjsRouteImport
       parentRoute: typeof rootRouteImport
     }
-    '/nested.js/script.js': {
-      id: '/nested.js/script.js'
+    '/script.js': {
+      id: '/script.js'
       path: '/script.js'
-      fullPath: '/nested.js/script.js'
-      preLoaderRoute: typeof NestedDotjsScriptDotjsRouteImport
-      parentRoute: typeof NestedDotjsRoute
+      fullPath: '/script.js'
+      preLoaderRoute: typeof ScriptDotjsRouteImport
+      parentRoute: typeof rootRouteImport
     }
     '/nested.js/double.ext.js': {
       id: '/nested.js/double.ext.js'
@@ -111,6 +104,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof NestedDotjsDoubleDotextDotjsRouteImport
       parentRoute: typeof NestedDotjsRoute
     }
+    '/nested.js/script.js': {
+      id: '/nested.js/script.js'
+      path: '/script.js'
+      fullPath: '/nested.js/script.js'
+      preLoaderRoute: typeof NestedDotjsScriptDotjsRouteImport
+      parentRoute: typeof NestedDotjsRoute
+    }
   }
 }