refactor(router-core): add error when building route tree if trying to add children routes to an index route

Open Sheraff opened this issue 1 month ago • 3 comments

It seems some theoretically invalid route tree configurations used to work before https://github.com/TanStack/router/pull/5867 but don't work anymore.

This PR proposes that we add some runtime checks (when NODE_ENV !== 'production') to warn users of such patterns.

Those env checks persist in the dist build of tanstack/router-core distributed through npm

But get erased at build-time (tested w/ Vite rollup 7.1.12) when the production environment is set (vite build --mode production or simply vite build)

Summary by CodeRabbit

Bug Fixes
- Added development-time validation that surfaces clear errors for invalid route configurations—prevents index routes from having children and ensures parent/child route relationships are consistent, helping catch routing setup mistakes earlier.

Nov 18 '25 22:11 Sheraff

🤖 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 60e5fea9c778dfafe9d250388e6d23bb6e66b261

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

☁️ Nx Cloud last updated this comment at 2025-11-18 23:03:58 UTC

Nov 18 '25 22:11 nx-cloud[bot]

Walkthrough

Runtime validation is added (development-only) to BaseRoute construction and child attachment to ensure index routes (non-root routes whose fullPath ends with /) are not assigned child routes and parent-child relationships are consistent.

Changes

Cohort / File(s)	Summary
Route validation guards `packages/router-core/src/route.ts`	Adds two runtime invariant checks (guarded by `NODE_ENV !== 'production'`): one in `BaseRoute` constructor/init to validate parent-child integrity and one in child-attachment logic to prevent index routes (trailing `/` for non-root) from having children. No public API signatures changed.

Sequence Diagram(s)

sequenceDiagram
  participant Builder as RouterBuilder
  participant Base as BaseRoute (init / ctor)
  participant AddChildren as RouteAddChildren (attach children)
  participant Dev as Developer

  Note over Builder,Base: Route creation (dev-only validations applied)
  Builder->>Base: construct/init route with optional parent
  alt parent exists and is invalid index-parent or missing child relation
    Base-->>Dev: throw invariant error (parent-child integrity)
  else
    Base->>AddChildren: proceed to attach children (if any)
    alt route.fullPath ends with '/' and has children
      AddChildren-->>Dev: throw invariant error (index route cannot have children)
    else
      AddChildren->>Builder: children attached (success)
    end
  end

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Localized, small changes in a single file following a consistent pattern.
Low logic density: two development-only guard clauses.

Areas to review:

Correct detection of index routes (trailing / semantics for root vs non-root).
Clarity and correctness of invariant error messages.

Suggested reviewers

schiller-manuel

Poem

🐰 Hopping through paths with careful paws,

I check each parent, enforce the laws.
No index may sprout a child anew,
I thump and warn, "This won't do!"
Dev-time safety — hops for you ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and specifically describes the main change: adding error validation when children routes are added to index routes during route tree building.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

[ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

[ ] Create PR with unit tests
[ ] Post copyable unit tests in a comment
[ ] Commit unit tests in branch refactor-router-core-route-errors-w-index-children

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

Nov 18 '25 22:11 coderabbitai[bot]

More templates

@tanstack/arktype-adapter

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

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5897

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5897

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 60e5fea

Nov 18 '25 22:11 pkg-pr-new[bot]