Skip to content
Source
Sign inSign up
TanStack/router

fix(router-generator): type route-group layouts with full path `'/'` #8857

MergedSheraff(GitHub profile, opens in a new tab)merged 4 commits intomain fromrefs/pull/8857/headmerged by Sheraff(GitHub profile, opens in a new tab)

Split out of #8817 (a "before" change it already includes).

A pathless layout inside a route group, e.g. routes/(group)/_layout.tsx, was typed with fullPath: '' in FileRoutesByPath. At runtime the router gives it the full path '/', which is also what a pathless layout outside a group already gets in the types. Link from and useParams({ from }) follow this type.

Cause: inferFullPath strips /(group)/_layout down to /. That isn't empty, so the existing '' → '/' check doesn't apply, and dropping the trailing slash then leaves ''.

Fix: one condition. When dropping the trailing slash leaves an empty string, return '/'.

Generation is unchanged. checkRouteFullPathUniqueness keeps comparing the stripped path ('' for a route group's layout), so the full-path conflicts are exactly main's. Comparing '/' would make a group layout without child routes yet ((group)/_layout.tsx or (group)/route.tsx) conflict with index.tsx, a shape main generates. Skipping pathless layouts in the check instead would let a childless _auth.tsx through, which main refuses: the tree lists the index route first, and the router then matches / to the layout.

Effects:

  • In FileRoutesByPath, the group layout's fullPath goes from '' to '/'.
  • If no index route claims /, the layout now shows up under '/' in FileRoutesByFullPath/FileRoutesByTo. Before, the '' key was filtered out. A pathless layout outside a group already behaves this way, and #8817's routesByFullPath/routesByTo do the same.
  • Start's prerender path list (the other inferFullPath caller) skips pathless and group layouts (isNonPath), so it doesn't change.

Tests: tests/childless-pathless-layout.test.ts checks that a childless (group)/_layout.tsx and (marketing)/route.tsx still generate next to index.tsx, that a childless _auth.tsx there is still refused, and that foo/_layout.tsx (no foo.tsx) still conflicts with (group)/foo.tsx and foo_.tsx. I updated main's generator snapshots (route-groups, nested-route-groups-with-layouts-before-physical). The 6 committed route trees that have group layouts were regenerated through their app builds; each changes by one line. The *-esbuild-file-based e2e trees aren't produced by their builds, and #8817 doesn't touch them either, so I left them alone.

Validation: @tanstack/router-generator: test:unit, test:types, test:eslint and test:build pass; @tanstack/start-plugin-core: test:unit, test:types and test:eslint pass. The regenerated apps' builds pass, including tsc/vue-tsc --noEmit. Emitted client JS is unchanged: only types in routeTree.gen.ts change.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • Route-group layouts at the application root now use / as their full path, improving generated route metadata and route-path typing across supported frameworks.
    • Childless layouts alongside index routes are represented correctly. Layouts that conflict with another route at the same full path continue to trigger conflict errors.
  • Tests
    • Added coverage for root layouts, route groups, and duplicate full paths.
    1. 🦋 Changeset detected

      Latest commit: 23fd9c46385ee50ee2658d6514132ede78b5dfed

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 9 packages
      NameType
      @tanstack/router-generatorPatch
      @tanstack/router-cliPatch
      @tanstack/router-pluginPatch
      @tanstack/start-plugin-corePatch
      @tanstack/router-vite-pluginPatch
      @tanstack/react-start-rscPatch
      @tanstack/react-startPatch
      @tanstack/solid-startPatch
      @tanstack/vue-startPatch

      Not sure what this means? Click here to learn what changesets are.

      Click here if you're a maintainer who wants to add another changeset to this PR

    2. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-generator

    3. Review in Change Stack →

      No actionable comments were generated in the recent review.

      Walkthrough

      The generator now distinguishes stripped paths from inferred full paths. Route-group layouts with empty stripped paths receive / in generated metadata. Uniqueness checks use stripped paths, and tests cover childless layouts and conflicting paths.

      Changes: Route-group path metadata

      Layer / File(s)Summary
      Full-path inference and uniqueness checks
      packages/router-generator/src/utils.ts, packages/router-generator/tests/childless-pathless-layout.test.ts
      stripFullPath returns an empty string for paths made only of route groups and pathless segments. inferFullPath maps an empty result to /. Uniqueness checks compare stripped paths. Tests cover childless layouts beside an index route and conflicts at / and /foo.
      Generated route metadata
      packages/router-generator/tests/generator/route-groups/routeTree.snapshot.ts, packages/router-generator/tests/generator/nested-route-groups-with-layouts-before-physical/routeTree.snapshot.ts, e2e/*/basic-file-based*/src/routeTree.gen.ts, examples/vue/basic-file-based*/src/routeTree.gen.ts, .changeset/route-group-layout-full-path.md
      Snapshots and generated route trees set route-group layout fullPath values to /. The route-group snapshot adds / to its full-path and destination maps and unions. The changeset declares a patch release.

      Estimated code review effort: 2 (Simple) | ~10 minutes

      Change: Bug fix

      Suggested reviewers: schiller-manuel

      Merge Risk: Low · up to 23fd9

      Runtime behavior is safe, but the new public route-type contract lacks a direct regression test. The change is low risk to merge with that follow-up noted.

      Pre-merge checks: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…Write docstrings for the functions missing them to satisfy the coverage threshold.
      Passed Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely identifies the primary change: route-group layouts now use full path '/' in router-generator types.
      Description checkPassedThe description clearly explains the issue, cause, fix, compatibility behavior, tests, validation results, generated-file impact, and AI assistance. It does not reproduce the template headings or chec…
      Linked Issues checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck skipped because no linked issues were found for this pull request.
      Full details: Description check

      Explanation

      The description clearly explains the issue, cause, fix, compatibility behavior, tests, validation results, generated-file impact, and AI assistance. It does not reproduce the template headings or checklist, but it provides the required substantive information, including testing and release impact through the changeset.

      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 3 functions across 10 files. (1 skipped: 1 unsupported.)

      Resolution

      Write docstrings for the functions missing them to satisfy the coverage threshold.

      Finishing Touches
      Generate docstrings
      • Commit to this branch
      • Create a new PR
      Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR
      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      Share

      CodeRabbit Verify

      • Run CodeRabbit Verify to test the changes in this pull request.
      Recent review info
      Run configuration
      Commits

      Reviewing files that changed from the base of the PR and between e5a9b6917754e8d0c2c52d330e7bd215718f2e28 and 23fd9c46385ee50ee2658d6514132ede78b5dfed.

      Files selected for processing: 3
      • .changeset/route-group-layout-full-path.md
      • packages/router-generator/src/utils.ts
      • packages/router-generator/tests/childless-pathless-layout.test.ts
      Files with no reviewable changes: 1
      • .changeset/route-group-layout-full-path.md

      Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

    4. 🚀 Changeset Version Preview

      2 package(s) bumped directly, 7 bumped as dependents.

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/router-plugin1.168.48 → 1.169.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/router-generator1.167.46 → 1.167.47Changeset
      @tanstack/react-start1.169.4 → 1.169.5Dependent
      @tanstack/react-start-rsc0.1.65 → 0.1.66Dependent
      @tanstack/router-cli1.167.46 → 1.167.47Dependent
      @tanstack/router-vite-plugin1.167.48 → 1.167.49Dependent
      @tanstack/solid-start1.169.4 → 1.169.5Dependent
      @tanstack/start-plugin-core1.171.55 → 1.171.56Dependent
      @tanstack/vue-start1.169.4 → 1.169.5Dependent
    5. View your CI Pipeline Execution ↗ for commit 23fd9c46385ee50ee2658d6514132ede78b5dfed

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded10m 14sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 28sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-11-03 17:57:58 UTC

      • Fix comments: Fix CodeRabbit comments on this PR
      OutdatedResolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    6. Bundle Size Benchmarks

      This pull request does not affect bundle size in any measured scenario.

    7. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/@tanstack/arktype-adapter@8857

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

      npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8857

      @tanstack/history

      npm i https://pkg.pr.new/@tanstack/history@8857

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

      npm i https://pkg.pr.new/@tanstack/react-start@8857

      @tanstack/react-start-client

      npm i https://pkg.pr.new/@tanstack/react-start-client@8857

      @tanstack/react-start-rsc

      npm i https://pkg.pr.new/@tanstack/react-start-rsc@8857

      @tanstack/react-start-server

      npm i https://pkg.pr.new/@tanstack/react-start-server@8857

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

      npm i https://pkg.pr.new/@tanstack/solid-start@8857

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/@tanstack/solid-start-client@8857

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/@tanstack/solid-start-server@8857

      @tanstack/start-client-core

      npm i https://pkg.pr.new/@tanstack/start-client-core@8857

      @tanstack/start-fn-stubs

      npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8857

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/@tanstack/start-plugin-core@8857

      @tanstack/start-server-core

      npm i https://pkg.pr.new/@tanstack/start-server-core@8857

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/@tanstack/start-storage-context@8857

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/@tanstack/valibot-adapter@8857

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8857

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

      npm i https://pkg.pr.new/@tanstack/vue-start@8857

      @tanstack/vue-start-client

      npm i https://pkg.pr.new/@tanstack/vue-start-client@8857

      @tanstack/vue-start-server

      npm i https://pkg.pr.new/@tanstack/vue-start-server@8857

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/@tanstack/zod-adapter@8857

      commit: 23fd9c4

      • Fix comments: Fix CodeRabbit comments on this PR
      OutdatedResolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    8. Sheraff(GitHub profile, opens in a new tab)replied on packages/router-generator/tests/childless-pathless-layout.test.ts line 70

      Keeping this as a standalone test. What it checks is that generation no longer throws for these shapes (all 3 threw "Conflicting configuration paths" before the fix). The FileRoutesById entry and the root's children both come from the same route nodes, so the substring check is enough here. A new tests/generator/<case> fixture would add expected text snapshots, and the follow-up generator rewrite (#8817) deletes all of those. This file runs unchanged on that rewrite's generator.

    9. Sheraff(GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 950

      Confirmed: foo/_layout.tsx without foo.tsx is given path: '/foo', and main rejected it next to (group)/foo.tsx or foo_.tsx. Fixed in e5a9b69177: the uniqueness check skips only routes the tree gives no path, using the same hasPathOption condition as the printer. Both pairs have regression tests.

      • Fix comments: Fix CodeRabbit comments on this PR
      OutdatedResolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    10. coderabbitai[bot](GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 950

      @Sheraff Thanks for the fix. The supplied code uses hasPathOption for both path emission and the uniqueness check. This keeps path-bearing layouts in conflict detection and excludes layouts without a generated path. This addresses the finding.


      Learnings added
      Learnt from: Sheraff
      Repo: TanStack/router PR: 8857
      File: packages/router-generator/src/generator.ts:0-0
      Timestamp: 2026-11-03T17:32:22.109Z
      Learning: Within repository "TanStack/router", only for files matching one of ["packages/router-generator/src/generator.ts"]: When reviewing path emission or full-path uniqueness filtering in packages/router-generator/src/generator.ts, ensure pathless_layout routes with a nonempty cleanedPath receive a path property even when isNonPath is true. For otherwise eligible leaf, non-lazy routes, use the same path-emission condition for uniqueness checking: include path-bearing layouts and exclude layouts without a generated path. Do not exclude all isNonPath routes.

      Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


      Learnings used
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 6120
      File: packages/router-generator/src/generator.ts:654-657
      Timestamp: 2025-12-17T02:17:47.423Z
      Learning: In packages/router-generator/src/generator.ts, enforce that pathless_layout routes with a cleanedPath must have a path property. This is required because child routes inherit the parent's path; without a path property, the full path will not resolve correctly at runtime. Update the route type/validation to require path for such routes and add tests ensuring that a pathless_layout with cleanedPath provides a valid fullPath resolution.

      If you found this review helpful, would you consider giving us a shout-out on X?

      Thank you for using CodeRabbit!

      Review thread resolved.

      You are interacting with an AI system.
    11. coderabbitai[bot](GitHub profile, opens in a new tab)replied on packages/router-generator/tests/childless-pathless-layout.test.ts line 70

      @Sheraff You're right. The awaited generator.run() makes each case fail if generation throws, which covers this regression. My request added route-attachment checks beyond that scope. Keeping the standalone test is reasonable; I withdraw the fixture-migration request.


      Learnings used
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: packages/router-generator/AGENTS.md:0-0
      Timestamp: 2026-10-25T23:59:37.202Z
      Learning: Applies to packages/router-generator/** : Source excerpt:
      # Route generator
      
      - Add generation cases under `tests/generator/<case>/`. Read [`tests/generator.test.ts`](tests/generator.test.ts) for per-case configuration and preprocessing. Change route inputs/configuration or templates, then regenerate route trees and expected snapshots through the test harness.

      Review thread resolved.

      You are interacting with an AI system.
    12. Sheraff(GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 961

      Confirmed on main's router: with the index route listed first, a childless _auth.tsx, (g)/_layout or (marketing) route next to it takes /. Fixed in 23fd9c4638 by keeping main's full-path conflict check unchanged, so this PR only changes the types: a childless _auth.tsx next to index.tsx is refused again, with a test. The route-group case generates as it did on main. Its / shadowing predates this PR, which doesn't change the runtime tree. Changing the matcher in router-core is out of scope here.

    13. Sheraff(GitHub profile, opens in a new tab)replied on packages/router-generator/src/utils.ts lines 949 to 951

      Not adding a fixture tests.test-d.ts here. On main, the updated route-groups and nested-route-groups-with-layouts-before-physical snapshots pin fullPath: '/' and the '/' entries in FileRoutesByFullPath/FileRoutesByTo. The type-level check against the real router is tests/integration/fixture-types-physical.test.ts, which type-checks these same fixtures. It comes with the test-harness PR that ports the compiler rewrite's (#8817) tests to main. A new fixture tests.test-d.ts would also never run on #8817, which only type-checks fixture test files wired through its integration tests.

    14. Merging this PR will improve performance by 6.64%

      1 warning, 1 note

      :warning: 46 benchmarks are dominated by system calls

      System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

      Learn more about system calls

      See affected benchmarks

      :information_source: 3 benchmarks have no flamegraph

      The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.

      See affected benchmarks

      ⚡ 1 improved benchmark ✅ 193 untouched benchmarks ⏩ 3 skipped benchmarks1

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ⚡Memorymem client navigation-churn (solid)110.2 KB103.4 KB+6.64%

      Tip

      Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


      Comparing router-generator/route-group-layout-full-path (23fd9c4) with main (13b6256) Open in CodSpeed

      Footnotes

      1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

    15. coderabbitai[bot](GitHub profile, opens in a new tab)replied on packages/router-generator/src/utils.ts lines 949 to 951

      @Sheraff Understood. I withdraw the request for a separate fixture tests.test-d.ts. I applied the general packages/** type-test guidance without accounting for the generator’s test harness.

      The updated snapshots cover the generated declarations. Your explanation places the real-router type check in tests/integration/fixture-types-physical.test.ts in the test-harness PR. An unwired fixture test would not add coverage. I have not independently verified that companion PR.


      Learnings used
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: packages/router-generator/AGENTS.md:0-0
      Timestamp: 2026-10-25T23:59:37.202Z
      Learning: Applies to packages/router-generator/** : Source excerpt:
      # Route generator
      
      - Add generation cases under `tests/generator/<case>/`. Read [`tests/generator.test.ts`](tests/generator.test.ts) for per-case configuration and preprocessing. Change route inputs/configuration or templates, then regenerate route trees and expected snapshots through the test harness.
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: packages/AGENTS.md:0-0
      Timestamp: 2026-10-25T23:26:49.316Z
      Learning: Applies to packages/** : Source excerpt:
      # Packages
      
      ## Tests
      
      - For public type changes, add `*.test-d.*` inference regressions and run both unit and type targets. React/Solid Router's TypeScript compiler matrix checks `src`; Vitest runs their inference tests. For changes to inference cost, follow the [type-safety performance guidance](../docs/router/guide/type-safety.md#performance-recommendations); `test:perf` measures runtime, not compiler cost.

      Review thread resolved.

      You are interacting with an AI system.
    16. coderabbitai[bot](GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 961

      @Sheraff Thanks for the clarification and fix in 23fd9c4638. The supplied generator.ts restores the leaf, non-lazy uniqueness filter without hasPathOption(d).

      Restoring the existing conflict behavior addresses the regression without a matcher change. I retract the requirement to fix route-group / shadowing in this PR. That behavior predates this PR and belongs in a separate router-core change.

      Would you like me to open a follow-up issue for the existing route-group shadowing?


      Learnings used
      Learnt from: Sheraff
      Repo: TanStack/router
      
      Timestamp: 2026-11-03T17:32:23.337Z
      Learning: Within repository "TanStack/router", only for files matching one of ["packages/router-generator/src/generator.ts"]: When reviewing path emission or full-path uniqueness filtering in packages/router-generator/src/generator.ts, ensure pathless_layout routes with a nonempty cleanedPath receive a path property even when isNonPath is true. For otherwise eligible leaf, non-lazy routes, use the same path-emission condition for uniqueness checking: include path-bearing layouts and exclude layouts without a generated path. Do not exclude all isNonPath routes.

      If you found this review helpful, would you consider giving us a shout-out on X?

      Thank you for using CodeRabbit!

      Review thread resolved.

      You are interacting with an AI system.

Sign in to join this conversation.