fix: Fix conflicting paths error when lazy loading layout and index r…

[schiller-manuel]

…outes without anchor files

fixes #6230

Summary by CodeRabbit

• Bug Fixes

  • Improved parent route resolution for cases where initial lookups fail, ensuring correct route hierarchy.
  • Ensured routes are always registered by path so child routes (including lazy-loaded ones) reliably locate parents.

• Tests

  • Added tests and generated snapshots for lazy-only layouts and index routes to validate routing behavior and types.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces fallback parent-resolution in the route generator: when prefixMap lookup fails, the code walks up path segments and consults a route-by-path registry; also ensures any node with a routePath is registered in routeNodesByPath so children (including from lazy-only files) can find parents. Test snapshot added.

Changes

Cohort / File(s)	Summary
Generator logic packages/router-generator/src/generator.ts	Add fallback parent resolution by walking path segments and checking acc.routeNodesByPath; always register nodes with routePath into routeNodesByPath (including virtual/lazy-only nodes).
Lazy-only test routes packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/__root.tsx, packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx, packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.index.lazy.tsx	New test route files: root route, lazy layout /path, and lazy index /path/.
Generated route tree snapshot packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts	New generated snapshot describing route nodes, parent/child wiring, type interfaces (e.g., FileRoutesByFullPath, FileRouteTypes), module augmentation, and composed routeTree for the test case.

Sequence Diagram(s)

(omitted — changes are internal generator logic and tests; sequence diagrams not required)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(router-generator): allow escaping any special string in file-based routing #6156 — Modifies generator.ts parent-resolution and path handling; closely related changes in the same area.
• fix: generator perf and pathless routes relative to parent  #6121 — Improves parent-route lookup in handleNode; shares parent-resolution logic changes.
• fix: ignore route pieces in RoutePrefixMap #6186 — Addresses parent-selection for lazy-only/route-piece nodes; tackles the same parent-resolution class of bug.

Suggested Reviewers

• schiller-manuel
• nlynzaad

Poem

🐇 I hop the paths both short and long,
I stitch the parents, right the wrong,
Where lazy leaves once lost their place,
I bind the tree, each route—embrace! ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: fixing a conflicting paths error when lazy loading layout and index routes, which directly addresses the linked issue #6230.
Linked Issues check	✅ Passed	The code changes implement a fallback mechanism to resolve parent nodes and ensure route registration by path, which directly addresses the conflicting paths error reported in issue #6230 [#6230].
Out of Scope Changes check	✅ Passed	All changes are scoped to fixing the lazy-loading conflict: the generator logic fix, test route files, and snapshot are directly related to resolving the reported issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b12a798 and 4227777.

📒 Files selected for processing (5)

• packages/router-generator/src/generator.ts
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/__root.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.index.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/router-generator/src/generator.ts
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/__root.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.index.lazy.tsx

🧰 Additional context used

📓 Path-based instructions (2)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript strict mode with extensive type safety for all code

Files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

**/*.{js,ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Implement ESLint rules for router best practices using the ESLint plugin router

Files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

🧠 Learnings (8)

📓 Common learnings

Learnt from: schiller-manuel
Repo: TanStack/router PR: 6120
File: packages/router-generator/src/generator.ts:654-657
Timestamp: 2025-12-17T02:17:55.086Z
Learning: In `packages/router-generator/src/generator.ts`, pathless_layout routes must receive a `path` property when they have a `cleanedPath`, even though they are non-path routes. This is necessary because child routes inherit the path from their parent, and without this property, child routes would not have the correct full path at runtime.

Learnt from: Sheraff
Repo: TanStack/router PR: 6171
File: packages/router-core/src/new-process-route-tree.ts:898-898
Timestamp: 2025-12-21T12:52:35.231Z
Learning: In `packages/router-core/src/new-process-route-tree.ts`, the matching logic intentionally allows paths without trailing slashes to match index routes with trailing slashes (e.g., `/a` can match `/a/` route), but not vice-versa (e.g., `/a/` cannot match `/a` layout route). This is implemented via the condition `!pathIsIndex || node.kind === SEGMENT_TYPE_INDEX` and is a deliberate design decision to provide better UX by being permissive with missing trailing slashes.

Learnt from: nlynzaad
Repo: TanStack/router PR: 5402
File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
Timestamp: 2025-10-08T08:11:47.088Z
Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

📚 Learning: 2025-12-17T02:17:55.086Z

Learnt from: schiller-manuel
Repo: TanStack/router PR: 6120
File: packages/router-generator/src/generator.ts:654-657
Timestamp: 2025-12-17T02:17:55.086Z
Learning: In `packages/router-generator/src/generator.ts`, pathless_layout routes must receive a `path` property when they have a `cleanedPath`, even though they are non-path routes. This is necessary because child routes inherit the path from their parent, and without this property, child routes would not have the correct full path at runtime.

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-10-08T08:11:47.088Z

Learnt from: nlynzaad
Repo: TanStack/router PR: 5402
File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
Timestamp: 2025-10-08T08:11:47.088Z
Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-10-01T18:31:35.420Z

Learnt from: schiller-manuel
Repo: TanStack/router PR: 5330
File: e2e/react-start/custom-basepath/src/routeTree.gen.ts:58-61
Timestamp: 2025-10-01T18:31:35.420Z
Learning: Do not review files named `routeTree.gen.ts` in TanStack Router repositories, as these are autogenerated files that should not be manually modified.

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-12-21T12:52:35.231Z

Learnt from: Sheraff
Repo: TanStack/router PR: 6171
File: packages/router-core/src/new-process-route-tree.ts:898-898
Timestamp: 2025-12-21T12:52:35.231Z
Learning: In `packages/router-core/src/new-process-route-tree.ts`, the matching logic intentionally allows paths without trailing slashes to match index routes with trailing slashes (e.g., `/a` can match `/a/` route), but not vice-versa (e.g., `/a/` cannot match `/a` layout route). This is implemented via the condition `!pathIsIndex || node.kind === SEGMENT_TYPE_INDEX` and is a deliberate design decision to provide better UX by being permissive with missing trailing slashes.

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-12-06T15:03:07.223Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T15:03:07.223Z
Learning: Use file-based routing in `src/routes/` directories or code-based routing with route definitions

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx
• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-12-06T15:03:07.223Z

Learnt from: CR
Repo: TanStack/router PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T15:03:07.223Z
Learning: Applies to **/*.{js,ts,tsx} : Implement ESLint rules for router best practices using the ESLint plugin router

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

📚 Learning: 2025-11-02T16:16:24.898Z

Learnt from: nlynzaad
Repo: TanStack/router PR: 5732
File: packages/start-client-core/src/client/hydrateStart.ts:6-9
Timestamp: 2025-11-02T16:16:24.898Z
Learning: In packages/start-client-core/src/client/hydrateStart.ts, the `import/no-duplicates` ESLint disable is necessary for imports from `#tanstack-router-entry` and `#tanstack-start-entry` because both aliases resolve to the same placeholder file (`fake-start-entry.js`) in package.json during static analysis, even though they resolve to different files at runtime.

Applied to files:

• packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts

🧬 Code graph analysis (2)

packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx (2)

packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/__root.tsx (1)

• Route (2-2)

packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.index.lazy.tsx (1)

• Route (2-4)

packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts (2)

packages/router-generator/tests/generator/file-modification-verboseFileRoutes-false/routeTree.snapshot.ts (2)

• FileRoutesByPath (102-152)
• FileRouteTypes (80-93)

packages/router-generator/tests/generator/file-modification-verboseFileRoutes-true/routeTree.snapshot.ts (1)

• FileRoutesByPath (97-133)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Preview
• GitHub Check: Test

🔇 Additional comments (2)

packages/router-generator/tests/generator/lazy-only-layout-and-index/routes/path.lazy.tsx (1)

1-4: LGTM! Test fixture correctly demonstrates the lazy layout route scenario.

This test fixture properly defines a lazy layout route at '/path' using createLazyFileRoute, which together with the corresponding index route at '/path/' (from path.index.lazy.tsx) validates the fix for issue #6230's conflicting paths error.

packages/router-generator/tests/generator/lazy-only-layout-and-index/routeTree.snapshot.ts (1)

1-89: Skipping review per established guidelines.

This is an autogenerated snapshot file used to verify the router generator's output and should not be reviewed or modified.

Based on learnings, test snapshot files matching the pattern packages/router-generator/tests/generator/**/routeTree*.snapshot.ts are fixtures that are intentionally preserved as-is to validate the generator's behavior.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

---

View your CI Pipeline Execution ↗ for commit 4227777

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	14m 43s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	35s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-12-30 01:54:39 UTC

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6251

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6251

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6251

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6251

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6251

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6251

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6251

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6251

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6251

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6251

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6251

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6251

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6251

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6251

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6251

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6251

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6251

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6251

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6251

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6251

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6251

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6251

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6251

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6251

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6251

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6251

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6251

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6251

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6251

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6251

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6251

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6251

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6251

@tanstack/vue-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6251

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6251

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6251

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6251

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6251

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6251

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6251

commit: 4227777