Skip to content
Source
Sign inSign up
TanStack/router

refactor(router-core): Process routeTree into segment tree instead of flatRoutes #5722

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

This PR rewrites processRouteTree to yield a trie-like tree of segments. This replaces

  • packages/router-core/src/process-route-tree.ts
  • parts of packages/router-core/src/path.ts

Matching complexity now grows linearly with the number of segments (i.e. /a/b/c => 3 segments), as opposed to the previous algorithm that was correlated with the number of routes.

Goals:

  • faster pre-processing at start-time
  • faster matching at run-time
  • more consistent priority matching

Non-goals:

  • low RAM usage

Fixes https://github.com/TanStack/router/issues/5635 Fixes https://github.com/TanStack/router/issues/5674 Fixes https://github.com/TanStack/router/issues/5799

to-do:

  • fix "off-by-1" (leading/trailing /)
  • implement sorting of same-type siblings at the node level (case sensitivity, prefix/suffix length)
  • implement single-match ("does A match B")
  • implement all-route-match ("which route does A match")
  • bench pre-processing against current implementation
  • bench single-match against current implementation
  • bench all-route-match against current implementation
  • fix not found page
  • fix URL param encoding (see failing tests)
  • write more tests and clean up existing tests
  • document priorities and "matching logic quirks"

Bench:

  • pre-processing
    • consistently >2x faster
  • needle-in-a-haystack route matching
    • for very small route trees: 3.5x faster
    • for very large route trees: 950x faster (430 routes)
    • non-matching: 90x faster (430 routes, random path "that almost matches" requested, this is a worst-case-scenario simulation)
  • 1-to-1 route matching (useMatchRoute)
    • for very simple routes: 1.5x slower
    • for very complex routes: 1x
  • resolvePath
    • 2.7x faster (added a LRU cache to this, it's called a lot and is easy to cache, but function itself could be improved)
  • interpolatePath
    • 1.4x faster

Notes:

  • in its current implementation, 1-to-1 route matching (useMatchRoute) does not care about the routeTree. It will match 2 arbitrary strings. This can lead to unexpected results, and is probably not the behavior we want in the long term. For now, this PR implements findSingleMatch to preserve that behavior, and this method is slower than the current implementation. However, when we switch to matching against the routeTree (using findRouteMatch instead), it will be faster.
  • We use an int32 bitmask to keep track of skipped optional segments, which means that segments beyond the 32nd segment cannot be optional
  • We use a UInt16Array to keep track of some indices, which also has a theoretical limit (65536 chars) but it is greater than the maximum length of URLs supported by most browsers (AFAIK, Chrome has the lowest limit, Firefox is exactly 65536, and Safari supports longer)
  • the segment tree can be built in several passes (like we do for route masks, provided as a list instead of a tree), so it is compatible with a "fog of war" approach. However, the tree must be walked to re-sort siblings after a batch of modifications.

Future improvements:

  • we could consider flattening the tree branches that contain a single child at each node
  • removing route-by-route case sensitivity configuration (keep global option) could yield some performance improvements
  • we could take inspiration from find-my-way (router for fastify) and use nodes that are smaller than a full pathname segment. This yields a structure close to a radix tree, which could perform better.

Summary by CodeRabbit

  • Deprecations

    • caseSensitive on match-route options is deprecated; use route- or router-level case sensitivity.
  • Breaking Changes

    • Legacy path parsing/matching public APIs removed; integrations must adopt the new route-tree pipeline.
    • DevTools explorer no longer exposes flatRoutes.
  • New Features

    • New processed route-tree matcher with revamped path resolution and interpolation for more accurate matching and params.
  • Tests

    • Added and updated tests covering the new route-tree matcher and parsing semantics.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core

    2. Walkthrough

      Replaces the legacy pathname parser and route-tree processor with a new segment-trie processor, moves parsing/matching primitives into a new module, updates path utilities to use the segment model, replaces RouterCore's flatRoutes with processedTree and simplifies getMatchedRoutes, updates HMR and tests accordingly, and marks MatchRouteOptions.caseSensitive as deprecated.

      Changes

      Cohort / File(s)Summary
      Documentation & Deprecation
      docs/router/framework/react/api/router/MatchRouteOptionsType.md, packages/router-core/src/Matches.ts
      caseSensitive?: boolean annotated as deprecated in docs and JSDoc; guidance added to configure case sensitivity at route or router level.
      Removed Legacy Route Processor
      packages/router-core/src/process-route-tree.ts
      Entire file removed — previous route-tree building, scoring, sorting, flat route generation, and related exported types/functions deleted.
      New Route Processor & Parser
      packages/router-core/src/new-process-route-tree.ts
      New segment-based parser/matcher added: parseSegment, segment node types/factories, trie construction, deterministic node sorting, matching primitives, param extraction, caching and public APIs (processRouteTree, processFlatRouteList, findRouteMatch, findFlatMatch, findSingleMatch, trimPathRight, etc.).
      Path Utilities Refactor
      packages/router-core/src/path.ts
      Path utilities rewritten to use the new segment model: added joinPaths, cleanPath, trimPath*, removeTrailingSlash, exactPathTest, resolvePath; interpolatePath reimplemented; legacy parse/match exports and old Segment constants removed.
      Router Core Migration
      packages/router-core/src/router.ts
      Replaced public flatRoutes with processedTree: ProcessedTree<...>; getMatchedRoutes simplified to accept only pathname and return foundRoute; internal calls migrated to new-process-route-tree APIs and caches updated.
      Barrel & Framework Re-exports
      packages/router-core/src/index.ts, packages/react-router/src/index.tsx, packages/solid-router/src/index.tsx
      Removed re-exports of legacy path APIs/types: parsePathname, matchPathname, matchByPath, Segment; removed process-route-tree related exports from barrels.
      Call Site & Usage Adjustments
      packages/react-router/src/useBlocker.tsx, packages/solid-router/src/useBlocker.tsx, packages/start-server-core/src/createStartHandler.ts
      Simplified router.getMatchedRoutes calls by dropping explicit second argument (now called with only pathname).
      HMR & Plugin Updates
      packages/router-plugin/src/core/route-hmr-statement.ts
      Updated imports to include AnyRouter; replaced flatRoutes in-place swap with segment-tree walk/replace (walkReplaceSegmentTree), cleared caches, and updated processedTree nodes for HMR updates.
      Devtools Surface
      packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx
      Removed flatRoutes key from explorerState shaping; devtools explorer no longer exposes flatRoutes.
      Tests: New & Updated
      packages/router-core/tests/new-process-route-tree.test.ts, packages/router-core/tests/match-by-path.test.ts, packages/router-core/tests/optional-path-params*.test.ts, packages/router-core/tests/path.test.ts
      New tests for the new processor added; many tests updated to import parsing/matching primitives from new-process-route-tree, to create processedTree via processRouteTree, and to align expectations with new parsing semantics (empty root pathname segment, unprefixed param names, etc.).
      Framework Barrel Adjustments
      packages/react-router/src/index.tsx, packages/solid-router/src/index.tsx
      Dropped legacy parse/match exports and Segment type from framework barrels.

      Sequence Diagram(s)

      sequenceDiagram
          participant Dev as Developer
          participant RouterCore
          participant NewProc as new-process-route-tree
          participant PathUtil as path.ts
      
          rect rgb(230,245,234)
          Note over RouterCore,NewProc: Build processed route tree
          Dev->>RouterCore: buildRouteTree(routeTree)
          RouterCore->>NewProc: processRouteTree(routeTree, caseSensitive)
          NewProc->>NewProc: parseSegment / build trie
          NewProc-->>RouterCore: processedTree
          end
      
          rect rgb(245,245,230)
          Note over PathUtil,NewProc: Interpolation uses segment model
          Dev->>PathUtil: interpolatePath / resolvePath(...)
          PathUtil->>NewProc: parseSegment (traverse pattern)
          NewProc-->>PathUtil: segment node data
          PathUtil-->>Dev: final path
          end
      
          rect rgb(230,245,234)
          Note over RouterCore,NewProc: Runtime matching
          Dev->>RouterCore: getMatchedRoutes(pathname)
          RouterCore->>NewProc: findRouteMatch(pathname, processedTree)
          NewProc->>NewProc: trie traversal -> extractParams
          NewProc-->>RouterCore: matchedRoutes + foundRoute + params
          RouterCore-->>Dev: match result
          end

      Estimated code review effort

      🎯 4 (Complex) | ⏱️ ~60 minutes

      • Focus review on:
        • packages/router-core/src/new-process-route-tree.ts — parser/trie correctness, optional/wildcard/param edge cases, cache semantics.
        • packages/router-core/src/path.ts — interpolatePath and trailing-slash/encoding correctness.
        • packages/router-core/src/router.ts — migration from flatRoutes to processedTree and updated getMatchedRoutes usage.
        • Tests & barrels — ensure all removed exports are replaced and tests reflect new semantics.
      • TanStack/router#5128 — related refactor/replacement of processRouteTree and route-tree processing.
      • TanStack/router#5169 — related changes to parse/match logic and path parsing behaviors.
      • TanStack/router#5710 — related HMR route-replacement changes touching route-hmr-statement and processedTree updates.

      Suggested reviewers

      • schiller-manuel
      • nlynzaad

      Poem

      🐇 I swapped old maps for branching trees, I parse each hop with nimble knees. Through segments, params, wild and neat, I match your routes with tiny feet. A carrot patch of tests — sweet treat!

      Pre-merge checks and finishing touches

      ❌ Failed checks (1 warning)
      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.You can run @coderabbitai generate docstrings to improve docstring coverage.
      ✅ Passed checks (2 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly describes the main refactoring: replacing flatRoutes with a segment tree-based route processing system, which aligns with the substantial changes across router-core.
      Description Check✅ PassedCheck 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-process-route-tree-into-segment-tree`

      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. View your CI Pipeline Execution ↗ for commit b6570e3c3f3b9fd7cff1ecf2ff4d3f3757987541

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

      ☁️ Nx Cloud last updated this comment at 2025-11-15 12:32:53 UTC

    4. More templates

      @tanstack/arktype-adapter

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

      @tanstack/directive-functions-plugin

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

      @tanstack/eslint-plugin-router

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/server-functions-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/zod-adapter

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

      commit: b6570e3

    5. OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    6. OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    7. OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    8. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-devtools-core

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

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

    11. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-server-core

    12. Actionable comments posted: 3

      🧹 Nitpick comments (1)
      packages/router-core/tests/optional-path-params.test.ts (1)

      7-7: Type safety reduced in skipped tests.

      The change from Array<PathSegment> to Array<any> loses type safety. Since these tests are skipped for the WIP phase, this is acceptable, but if these tests are migrated later, restore proper typing.

      Also applies to: 11-11

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 54042014c5a7fbde2456657ce18b61b9c3231dd0 and 56808aa2e42335c5ea3621401a5e3ae5b6e90058.

      📒 Files selected for processing (15)
      • docs/router/framework/react/api/router/MatchRouteOptionsType.md (2 hunks)
      • packages/react-router/src/index.tsx (0 hunks)
      • packages/router-core/src/Matches.ts (1 hunks)
      • packages/router-core/src/Untitled-1.md (1 hunks)
      • packages/router-core/src/index.ts (0 hunks)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/router-core/src/path.ts (4 hunks)
      • packages/router-core/src/process-route-tree.ts (0 hunks)
      • packages/router-core/src/router.ts (11 hunks)
      • packages/router-core/tests/match-by-path.test.ts (3 hunks)
      • packages/router-core/tests/new-process-route-tree.test.ts (1 hunks)
      • packages/router-core/tests/optional-path-params-clean.test.ts (2 hunks)
      • packages/router-core/tests/optional-path-params.test.ts (1 hunks)
      • packages/router-core/tests/path.test.ts (2 hunks)
      • packages/solid-router/src/index.tsx (0 hunks)
      💤 Files with no reviewable changes (4)
      • packages/solid-router/src/index.tsx
      • packages/router-core/src/process-route-tree.ts
      • packages/router-core/src/index.ts
      • packages/react-router/src/index.tsx
      🧰 Additional context used
      📓 Path-based instructions (4)
      packages/router-core/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep framework-agnostic core router logic in packages/router-core/

      Files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/Matches.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/Matches.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      docs/**/*.{md,mdx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use internal docs links relative to the docs/ folder (e.g., ./guide/data-loading)

      Files:

      • docs/router/framework/react/api/router/MatchRouteOptionsType.md
      docs/{router,start}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place router docs under docs/router/ and start framework docs under docs/start/

      Files:

      • docs/router/framework/react/api/router/MatchRouteOptionsType.md
      🧠 Learnings (13)
      📓 Common learnings
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.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-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/Matches.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      📚 Learning: 2025-09-28T21:41:45.233Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{react-router,solid-router}/** : Implement React and Solid bindings/components only in packages/react-router/ and packages/solid-router/

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      📚 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-core/src/Untitled-1.md
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to docs/{router,start}/** : Place router docs under docs/router/ and start framework docs under docs/start/

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/src/path.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/Untitled-1.md
      • packages/router-core/src/path.ts
      📚 Learning: 2025-10-14T18:59:33.990Z
      Learnt from: FatahChan
      Repo: TanStack/router PR: 5475
      File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
      Timestamp: 2025-10-14T18:59:33.990Z
      Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.

      Applied to files:

      • packages/router-core/tests/new-process-route-tree.test.ts
      • docs/router/framework/react/api/router/MatchRouteOptionsType.md
      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      📚 Learning: 2025-10-09T12:59:02.129Z
      Learnt from: hokkyss
      Repo: TanStack/router PR: 5418
      File: e2e/react-start/custom-identifier-prefix/src/styles/app.css:19-21
      Timestamp: 2025-10-09T12:59:02.129Z
      Learning: In e2e test directories (paths containing `e2e/`), accessibility concerns like outline suppression patterns are less critical since the code is for testing purposes, not production use.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      🧬 Code graph analysis (4)
      packages/router-core/tests/new-process-route-tree.test.ts (1)
      packages/router-core/src/new-process-route-tree.ts (3)
      • processFlatRouteList (404-414)
      • processRouteTree (475-528)
      • findRouteMatch (454-463)
      packages/router-core/src/path.ts (3)
      packages/router-core/src/utils.ts (1)
      • last (191-193)
      packages/router-core/src/new-process-route-tree.ts (6)
      • parseSegment (23-115)
      • SegmentKind (8-8)
      • SEGMENT_TYPE_PATHNAME (3-3)
      • SEGMENT_TYPE_PARAM (4-4)
      • SEGMENT_TYPE_WILDCARD (5-5)
      • SEGMENT_TYPE_OPTIONAL_PARAM (6-6)
      packages/router-generator/src/utils.ts (1)
      • cleanPath (38-41)
      packages/router-core/src/new-process-route-tree.ts (2)
      packages/router-core/src/route.ts (3)
      • path (1551-1553)
      • RouteLike (1968-1979)
      • fullPath (1555-1557)
      packages/router-core/src/path.ts (1)
      • trimPathRight (32-34)
      packages/router-core/src/router.ts (3)
      packages/router-core/src/new-process-route-tree.ts (6)
      • ProcessedTree (391-402)
      • processRouteTree (475-528)
      • findFlatMatch (419-435)
      • findSingleMatch (440-452)
      • trimPathRight (467-469)
      • findRouteMatch (454-463)
      packages/router-core/src/route.ts (1)
      • RouteMask (1466-1475)
      packages/router-core/src/utils.ts (1)
      • deepEqual (333-387)
      ⏰ 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). (1)
      • GitHub Check: Test
      🔇 Additional comments (7)
      packages/router-core/src/Matches.ts (1)

      275-277: LGTM—Clear deprecation notice.

      The deprecation message provides clear guidance to configure case sensitivity at the route or router level instead of per-match options, aligning with the PR's move to route-tree-based configuration.

      packages/router-core/tests/match-by-path.test.ts (1)

      3-3: Skipped tests acceptable for WIP.

      The test suites are appropriately skipped as part of the API migration. Before merging, these tests should either be migrated to the new processedTree-based API or removed if the functionality is covered by new-process-route-tree.test.ts.

      Do you plan to migrate these test scenarios to the new API, or is the coverage in new-process-route-tree.test.ts sufficient?

      Also applies to: 78-78, 138-138

      packages/router-core/tests/path.test.ts (1)

      496-496: Skipped tests align with API migration.

      These test suites for matchPathname and parsePathname are appropriately skipped as these utilities are being replaced by the new route-tree processing approach.

      Also applies to: 722-722

      docs/router/framework/react/api/router/MatchRouteOptionsType.md (1)

      11-11: Documentation properly reflects API deprecation.

      The documentation updates clearly communicate the deprecation of caseSensitive and guide users to configure case sensitivity at the route or router level instead.

      Also applies to: 27-27, 32-32

      packages/router-core/tests/optional-path-params-clean.test.ts (1)

      8-8: Selective test skipping appropriate for migration.

      Good approach to skip only the parsePathname and matchPathname tests while keeping interpolatePath tests active, as interpolation logic remains relevant in the new API.

      Also applies to: 96-96

      packages/router-core/tests/optional-path-params.test.ts (1)

      5-5: Import update shows new module location.

      The segment type constants have been moved to new-process-route-tree.ts, establishing the new home for route processing types.

      packages/router-core/tests/new-process-route-tree.test.ts (1)

      1-428: Comprehensive test coverage for new route processing API.

      The test suite provides excellent coverage of the new processRouteTree and findRouteMatch functions, including:

      • Static and dynamic segments
      • Optional parameters with prefix/suffix
      • Wildcard routes
      • Fuzzy matching
      • Edge cases like multiple params at the same level

      The use of inline snapshots is well-suited for this WIP phase, making it easy to review the new matching behavior.

      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    13. Actionable comments posted: 1

      Caution

      Some comments are outside the diff and can’t be posted inline due to platform limitations.

      ⚠️ Outside diff range comments (2)
      packages/router-core/tests/optional-path-params-clean.test.ts (1)

      6-138: Remove references to deleted helpers in skipped suites.

      After dropping parsePathname/matchPathname from the public API, this test file no longer imports them, yet the bodies still reference the symbols. TypeScript errors out even though the suites are skipped. Please delete or stub these blocks so the file compiles.

      Apply this diff:

      -    describe.skip('parsePathname', () => {
      -      it('should parse single optional dynamic param', () => {
      -        const result = parsePathname('/posts/{-$category}')
      -        expect(result).toEqual([
      -          { type: SEGMENT_TYPE_PATHNAME, value: '/' },
      -          { type: SEGMENT_TYPE_PATHNAME, value: 'posts' },
      -          { type: SEGMENT_TYPE_OPTIONAL_PARAM, value: '$category' },
      -        ])
      -      })
      -      …
      -    })
      +    describe.skip('parsePathname', () => {
      +      // Removed along with parsePathname export; keeping the suite placeholder
      +      // avoids reintroducing the dependency while preserving history.
      +    })
      @@
      -    describe.skip('matchPathname', () => {
      -      it('should match optional dynamic params when present', () => {
      -        const result = matchPathname('/posts/tech', {
      -          to: '/posts/{-$category}',
      -        })
      -        expect(result).toEqual({ category: 'tech' })
      -      })
      -      …
      -    })
      +    describe.skip('matchPathname', () => {
      +      // Placeholder; original tests referenced removed matchPathname helper.
      +    })
      packages/router-core/src/router.ts (1)

      2617-2647: Update test file to use new getMatchedRoutes API signature.

      The test in packages/router-core/tests/processRouteTree.test.ts (lines 286-302) calls getMatchedRoutes with an outdated API signature. The function now accepts { pathname, routesById, processedTree } instead of { pathname, caseSensitive, routesByPath, routesById, flatRoutes }.

      Update the test call to pass processedTree from the processRouteTree result instead of the removed parameters. Additionally, note that the caseSensitive option is no longer configurable at the function level—getMatchedRoutes now always uses fuzzy matching (enabled at line 2630), which is intentional for server-side routing scenarios.

      ♻️ Duplicate comments (3)
      packages/react-router/src/useBlocker.tsx (1)

      180-180: API signature change mirrors solid-router implementation.

      This change is identical to the one in packages/solid-router/src/useBlocker.tsx at line 189, appropriately maintaining consistency across framework bindings.

      packages/router-core/src/new-process-route-tree.ts (1)

      540-546: Honor caseSensitive when caching single-route trees.

      findSingleMatch still hardcodes false, so any caller asking for a case-sensitive match gets a lowercased cache and the route keeps matching insensitive. This regresses router.matchRoute({ caseSensitive: true }).

      Apply this diff:

      -    parseSegments(false, data, { from }, 1, tree, 1)
      +    parseSegments(caseSensitive, data, { from }, 1, tree, 1)
      packages/router-core/src/path.ts (1)

      171-186: Optional param serialization now emits {−$$param}.

      Switching to the new segment parser is great, but this branch now injects a second $, so {-$id} becomes {−$$id} and prefixes/suffixes get the string "undefined" when absent. The generated template can’t be re-parsed or matched.

      Apply this diff:

      -    const prefix = segment.substring(0, data[1])
      -    const suffix = segment.substring(data[4]!, end)
      +    const prefix = segment.substring(0, data[1])
      +    const suffix = segment.substring(data[4]!, end)
      @@
      -      joined += `${prefix}{-$${value}}${suffix}`
      +      const safePrefix = prefix ?? ''
      +      const safeSuffix = suffix ?? ''
      +      joined += safePrefix + '{-$' + value + '}' + safeSuffix
      🧹 Nitpick comments (1)
      packages/router-core/src/router.ts (1)

      904-904: Consider improving type safety for processedTree generic parameters.

      The processedTree property uses any for the second and third generic parameters (TFlat and TSingle), which reduces type safety. While this may be acceptable for the initial refactor (given the PR is marked WIP), consider whether these can be properly typed based on the route tree structure.

      If the flat and single route types can be derived from TRouteTree, consider updating the type to:

      -processedTree!: ProcessedTree<TRouteTree, any, any>
      +processedTree!: ProcessedTree<TRouteTree, RouteMask<TRouteTree>, { from: string }>

      Or introduce helper types if the proper types can be inferred from the route tree.

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 56808aa2e42335c5ea3621401a5e3ae5b6e90058 and 162a3d75960e80379377e0b4b979699ba55212fd.

      📒 Files selected for processing (10)
      • packages/react-router/src/useBlocker.tsx (1 hunks)
      • packages/router-core/src/Matches.ts (1 hunks)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/router-core/src/path.ts (4 hunks)
      • packages/router-core/src/router.ts (10 hunks)
      • packages/router-core/tests/new-process-route-tree.test.ts (1 hunks)
      • packages/router-core/tests/optional-path-params-clean.test.ts (2 hunks)
      • packages/router-core/tests/optional-path-params.test.ts (1 hunks)
      • packages/solid-router/src/useBlocker.tsx (1 hunks)
      • packages/start-server-core/src/createStartHandler.ts (1 hunks)
      🚧 Files skipped from review as they are similar to previous changes (2)
      • packages/router-core/src/Matches.ts
      • packages/router-core/tests/optional-path-params.test.ts
      🧰 Additional context used
      📓 Path-based instructions (4)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/solid-router/src/useBlocker.tsx
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/start-server-core/src/createStartHandler.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/react-router/src/useBlocker.tsx
      • packages/router-core/src/new-process-route-tree.ts
      packages/{react-router,solid-router}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Implement React and Solid bindings/components only in packages/react-router/ and packages/solid-router/

      Files:

      • packages/solid-router/src/useBlocker.tsx
      • packages/react-router/src/useBlocker.tsx
      packages/router-core/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep framework-agnostic core router logic in packages/router-core/

      Files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/src/new-process-route-tree.ts
      packages/{*-start,start-*}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Name and place Start framework packages under packages/-start/ or packages/start-/

      Files:

      • packages/start-server-core/src/createStartHandler.ts
      🧠 Learnings (14)
      📓 Common learnings
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/
      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.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/solid-router/src/useBlocker.tsx
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/start-server-core/src/createStartHandler.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/react-router/src/useBlocker.tsx
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{react-router,solid-router}/** : Implement React and Solid bindings/components only in packages/react-router/ and packages/solid-router/

      Applied to files:

      • packages/solid-router/src/useBlocker.tsx
      • packages/react-router/src/useBlocker.tsx
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

      Applied to files:

      • packages/solid-router/src/useBlocker.tsx
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/start-server-core/src/createStartHandler.ts
      • packages/router-core/src/router.ts
      • packages/router-core/src/new-process-route-tree.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-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-10-09T12:59:02.129Z
      Learnt from: hokkyss
      Repo: TanStack/router PR: 5418
      File: e2e/react-start/custom-identifier-prefix/src/styles/app.css:19-21
      Timestamp: 2025-10-09T12:59:02.129Z
      Learning: In e2e test directories (paths containing `e2e/`), accessibility concerns like outline suppression patterns are less critical since the code is for testing purposes, not production use.

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/router.ts
      • packages/router-core/src/new-process-route-tree.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-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/router.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-10-14T18:59:33.990Z
      Learnt from: FatahChan
      Repo: TanStack/router PR: 5475
      File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
      Timestamp: 2025-10-14T18:59:33.990Z
      Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.

      Applied to files:

      • packages/router-core/tests/new-process-route-tree.test.ts
      📚 Learning: 2025-09-28T21:41:45.233Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.

      Applied to files:

      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/start-server-core/src/createStartHandler.ts
      • packages/router-core/src/path.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to docs/{router,start}/** : Place router docs under docs/router/ and start framework docs under docs/start/

      Applied to files:

      • packages/start-server-core/src/createStartHandler.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-devtools,*-router-devtools}/** : Keep router devtools packages in packages/router-devtools/ and packages/*-router-devtools/

      Applied to files:

      • packages/router-core/src/router.ts
      🧬 Code graph analysis (4)
      packages/router-core/tests/new-process-route-tree.test.ts (1)
      packages/router-core/src/new-process-route-tree.ts (3)
      • processFlatRouteList (494-504)
      • processRouteTree (572-632)
      • findRouteMatch (550-561)
      packages/router-core/src/path.ts (3)
      packages/router-core/src/utils.ts (1)
      • last (191-193)
      packages/router-core/src/new-process-route-tree.ts (6)
      • parseSegment (29-122)
      • SegmentKind (8-12)
      • SEGMENT_TYPE_PATHNAME (3-3)
      • SEGMENT_TYPE_PARAM (4-4)
      • SEGMENT_TYPE_WILDCARD (5-5)
      • SEGMENT_TYPE_OPTIONAL_PARAM (6-6)
      packages/router-generator/src/utils.ts (1)
      • cleanPath (38-41)
      packages/router-core/src/router.ts (3)
      packages/router-core/src/new-process-route-tree.ts (6)
      • ProcessedTree (481-492)
      • processRouteTree (572-632)
      • findFlatMatch (509-525)
      • findSingleMatch (530-548)
      • trimPathRight (564-566)
      • findRouteMatch (550-561)
      packages/router-core/src/route.ts (1)
      • RouteMask (1466-1475)
      packages/router-core/src/utils.ts (1)
      • deepEqual (333-387)
      packages/router-core/src/new-process-route-tree.ts (2)
      packages/router-core/src/route.ts (3)
      • path (1551-1553)
      • RouteLike (1968-1979)
      • fullPath (1555-1557)
      packages/router-core/src/path.ts (1)
      • trimPathRight (38-40)
      ⏰ 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). (1)
      • GitHub Check: Test
      🔇 Additional comments (6)
      packages/solid-router/src/useBlocker.tsx (1)

      189-189: API signature change is complete and consistent across the codebase.

      The GetMatchRoutesFn type definition at packages/router-core/src/router.ts:697 already enforces a single-argument signature: (pathname: string) => { ... }. All 7 callers across the codebase already use this pattern with no two-argument calls present. The change at line 189 in useBlocker.tsx is fully consistent with the existing router-core API and requires no further updates.

      packages/router-core/src/router.ts (5)

      1095-1118: LGTM!

      The buildRouteTree method has been correctly updated to use the new processRouteTree API, storing the result in processedTree instead of flatRoutes. The destructuring and assignment are consistent with the new architecture.


      1536-1542: LGTM!

      The getMatchedRoutes method has been correctly updated to match the new GetMatchRoutesFn signature, passing only pathname and delegating to the helper function with processedTree.


      2499-2524: LGTM with a note on parameter semantics.

      The matchRoute method has been correctly updated to use findSingleMatch from the new API. The logic for comparing params and search is preserved.

      Note: The findSingleMatch parameter names (from, path) may be a bit unintuitive here - from receives the route pattern (next.pathname) and path receives the location to test against (baseLocation.pathname). This is semantically correct for the matchRoute use case but worth documenting if not already clear in the function's JSDoc.


      1773-1789: No issues found — the return type structure is correct.

      The findFlatMatch function returns { route: T; params: Record<string, string> } | null (as confirmed by its delegation to findMatch at line 524 of new-process-route-tree.ts), and the usage in router.ts lines 1780-1781 correctly accesses match.params and match.route after the null check on line 1779.


      697-701: All callers properly updated for the new GetMatchRoutesFn signature.

      Verification confirms the signature simplification from (pathname, routePathname) to (pathname) is complete and consistent across the codebase. All five call sites (start-server-core, solid-router, react-router, and internal router usage) have been updated and correctly destructure the return value { matchedRoutes, foundRoute, routeParams }. No legacy calls with two parameters remain.

      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    14. Actionable comments posted: 3

      ♻️ Duplicate comments (1)
      packages/router-core/src/new-process-route-tree.ts (1)

      147-290: Fix depth propagation bug when reusing existing nodes.

      The depth tracking breaks when the loop reuses an existing node (lines 158-160, 173-175, 202-209, 239-246). When nextNode points to an existing node, the local depth variable is never synchronized with nextNode.depth, so subsequent iterations compute incorrect depths for newly created nodes. This corrupts the buildBranch array (line 716), causing extractParams to misalign parameter extraction.

      Apply this diff to fix depth propagation:

                 if (existingNode) {
                   nextNode = existingNode
                 } else {
                   node.static ??= new Map()
                   const next = createStaticNode<TRouteLike>(
                     route.fullPath ?? route.from,
                   )
                   next.parent = node
      -            next.depth = ++depth
      +            next.depth = node.depth + 1
                   nextNode = next
                   node.static.set(value, next)
                 }
                 if (existingNode) {
                   nextNode = existingNode
                 } else {
                   node.staticInsensitive ??= new Map()
                   const next = createStaticNode<TRouteLike>(
                     route.fullPath ?? route.from,
                   )
                   next.parent = node
      -            next.depth = ++depth
      +            next.depth = node.depth + 1
                   nextNode = next
                   node.staticInsensitive.set(name, next)
                 }
                 } else {
                   const next = createDynamicNode<TRouteLike>(
                     SEGMENT_TYPE_PARAM,
                     route.fullPath ?? route.from,
                     caseSensitive,
                     prefix,
                     suffix,
                   )
                   nextNode = next
      -            next.depth = ++depth
      +            next.depth = node.depth + 1
                   next.parent = node
                   node.dynamic ??= []
                   node.dynamic.push(next)
                 }
                 } else {
                   const next = createDynamicNode<TRouteLike>(
                     SEGMENT_TYPE_OPTIONAL_PARAM,
                     route.fullPath ?? route.from,
                     caseSensitive,
                     prefix,
                     suffix,
                   )
                   nextNode = next
                   next.parent = node
      -            next.depth = ++depth
      +            next.depth = node.depth + 1
                   node.optional ??= []
                   node.optional.push(next)
                 }
                 )
                 nextNode = next
                 next.parent = node
      -          next.depth = ++depth
      +          next.depth = node.depth + 1
                 node.wildcard ??= []
                 node.wildcard.push(next)
               }
             }
             node = nextNode
      +      depth = node.depth
           }
      🧹 Nitpick comments (2)
      packages/router-core/src/new-process-route-tree.ts (2)

      309-326: Add case-sensitivity and alphabetical fallback to sort criteria.

      The current comparator doesn't distinguish case-sensitive from case-insensitive routes, nor does it provide an alphabetical fallback for stable sorting when prefix/suffix scores are equal. Past review comments flagged these omissions. Case-sensitive routes should rank higher, and ties should break alphabetically.

      Apply this diff to add the missing criteria:

       function sortDynamic(
      -  a: { prefix?: string; suffix?: string },
      -  b: { prefix?: string; suffix?: string },
      +  a: { prefix?: string; suffix?: string; caseSensitive?: boolean; fullPath: string },
      +  b: { prefix?: string; suffix?: string; caseSensitive?: boolean; fullPath: string },
       ) {
         if (a.prefix && b.prefix && a.prefix !== b.prefix) {
           if (a.prefix.startsWith(b.prefix)) return -1
           if (b.prefix.startsWith(a.prefix)) return 1
         }
         if (a.suffix && b.suffix && a.suffix !== b.suffix) {
           if (a.suffix.endsWith(b.suffix)) return -1
           if (b.suffix.endsWith(a.suffix)) return 1
         }
         if (a.prefix && !b.prefix) return -1
         if (!a.prefix && b.prefix) return 1
         if (a.suffix && !b.suffix) return -1
         if (!a.suffix && b.suffix) return 1
      +  if (a.caseSensitive && !b.caseSensitive) return -1
      +  if (!a.caseSensitive && b.caseSensitive) return 1
      +  return a.fullPath.localeCompare(b.fullPath)
      -  return 0
       }

      Based on learnings


      693-693: Document bitmask limitation for optional parameters.

      The bitmask approach (lines 693, 793) limits the implementation to approximately 31 optional parameters per path, since JavaScript bitwise operations are 32-bit signed. For most use cases this is sufficient, but worth documenting as a constraint.

      Add a comment documenting the constraint:

             // Optional dynamic segments ({-$param})
      +      // Note: Bitmask approach limits the implementation to ~31 optional params per path
             optional: Array<DynamicSegmentNode<T>> | null

      Also applies to: 793-793

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 162a3d75960e80379377e0b4b979699ba55212fd and 58baf3e8158874b96a05f0b8598881e35cd76124.

      📒 Files selected for processing (2)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/solid-router/src/index.tsx (0 hunks)
      💤 Files with no reviewable changes (1)
      • packages/solid-router/src/index.tsx
      🧰 Additional context used
      📓 Path-based instructions (2)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/router-core/src/new-process-route-tree.ts
      packages/router-core/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep framework-agnostic core router logic in packages/router-core/

      Files:

      • packages/router-core/src/new-process-route-tree.ts
      🧠 Learnings (7)
      📓 Common learnings
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories
      📚 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-core/src/new-process-route-tree.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-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      🧬 Code graph analysis (1)
      packages/router-core/src/new-process-route-tree.ts (2)
      packages/router-core/src/route.ts (3)
      • path (1551-1553)
      • RouteLike (1968-1979)
      • fullPath (1555-1557)
      packages/router-core/src/path.ts (1)
      • trimPathRight (38-40)
      🔇 Additional comments (3)
      packages/router-core/src/new-process-route-tree.ts (3)

      29-122: LGTM: Clean segment parsing with appropriate fallback.

      The function correctly handles all segment types (static, wildcard, param, optional param) with early returns for common cases. The defensive fallback at lines 115-122 is appropriate even though it should theoretically never be reached.


      359-492: LGTM: Well-structured types and factory functions.

      The node factories correctly initialize all fields, and the comment at lines 377-379 about key ordering for V8 optimization is a good practice. Type definitions are comprehensive and properly discriminated.


      572-632: LGTM: Correct route tree processing with proper validation.

      The function correctly initializes depth at 0, validates for duplicate route IDs with invariant, and maintains both ID and path lookup maps. The trailing-slash preference at line 613 is reasonable for route resolution.

      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
      Resolvedby Sheraff(GitHub profile, opens in a new tab)
      OutdatedResolvedby Sheraff(GitHub profile, opens in a new tab)
    15. Actionable comments posted: 0

      ♻️ Duplicate comments (1)
      packages/router-core/src/new-process-route-tree.ts (1)

      147-291: Critical: Fix depth synchronization when reusing existing nodes.

      When an existing node is reused (lines 159, 174, 208, 245, etc.), the local depth variable is never updated to match that node's depth. This causes newly created sibling nodes to be assigned incorrect depth values, breaking the invariant that node.depth equals the node's distance from root.

      Example scenario:

      • First route /foo/bar creates foo (depth=1) and bar (depth=2)
      • Second route /foo/baz reuses foo node but leaves local depth=0
      • New node baz gets depth = ++depth = 1, but should be 2

      This breaks buildBranch (line 716) which uses node.depth as an array index, and causes extractParams bitmask alignment errors for optional parameters.

      Apply this fix after line 290 to resynchronize depth whenever we advance to the next node:

             }
             node = nextNode
      +      depth = node.depth
           }

      This ensures depth stays consistent whether we create a new node or reuse an existing one.

      🧹 Nitpick comments (2)
      packages/router-core/src/new-process-route-tree.ts (2)

      309-326: Sort logic is sound, but consider adding tie-breaker.

      The sortDynamic comparator correctly prioritizes longer/more-specific prefixes and suffixes, then presence of constraints. Ties return 0, relying on stable sort.

      For deterministic behavior across JS engines, consider adding an alphabetical tie-breaker (as noted in past comments), though this is acceptable for a WIP implementation.


      793-793: Note: Bitmask limits optional parameter depth to ~32 levels.

      The skipped bitmask uses (1 << depth) for tracking which optional parameters were skipped. JavaScript bitwise operations are limited to 32 bits, so route trees deeper than 32 levels with optional parameters may experience incorrect behavior due to bit overflow.

      This is likely acceptable for practical route trees, but worth documenting as a constraint.

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 162a3d75960e80379377e0b4b979699ba55212fd and 58baf3e8158874b96a05f0b8598881e35cd76124.

      📒 Files selected for processing (2)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/solid-router/src/index.tsx (0 hunks)
      💤 Files with no reviewable changes (1)
      • packages/solid-router/src/index.tsx
      🧰 Additional context used
      📓 Path-based instructions (2)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/router-core/src/new-process-route-tree.ts
      packages/router-core/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep framework-agnostic core router logic in packages/router-core/

      Files:

      • packages/router-core/src/new-process-route-tree.ts
      🧠 Learnings (7)
      📓 Common learnings
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/
      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-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-core/src/new-process-route-tree.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-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/new-process-route-tree.ts
      🧬 Code graph analysis (1)
      packages/router-core/src/new-process-route-tree.ts (2)
      packages/router-core/src/route.ts (3)
      • path (1551-1553)
      • RouteLike (1968-1979)
      • fullPath (1555-1557)
      packages/router-core/src/path.ts (1)
      • trimPathRight (38-40)
      🔇 Additional comments (6)
      packages/router-core/src/new-process-route-tree.ts (6)

      29-122: Well-structured segment parser.

      The parseSegment function correctly handles all four segment types (static, param, wildcard, optional) with prefix/suffix support. The use of early returns and regex patterns is clean and efficient.


      407-492: Type definitions are well-structured.

      The type hierarchy correctly models the segment tree structure with discriminated unions (StaticSegmentNode vs DynamicSegmentNode), and the RouteLike union elegantly handles both tree-based and flat route representations.


      611-616: Verify routesByPath collision handling is intentional.

      When multiple routes map to the same trimmed path, the implementation prefers routes ending with / (line 613). This means /foo and /foo/ both store under key /foo, but the trailing-slash variant wins.

      Verify this is the desired precedence, as it could be surprising when looking up routes by path.


      842-860: Wildcard suffix logic is correct but asymmetric.

      The wildcard matching checks prefix against the current part (line 846-848) but suffix against the last part (line 850-852). This asymmetry is correct: wildcards consume all remaining segments, so the suffix constraint applies to the final segment only.

      The implementation is correct for wildcard semantics.


      650-713: Parameter extraction logic is correct and clever.

      The extractParams function correctly handles all segment types, including the complex optional parameter skip detection via bitmask (line 693). String offset calculations for extracting parameter names from the route's fullPath are accurate.

      The optimization to defer param name extraction until match time (rather than storing in nodes) enables sharing nodes that differ only in param names.


      729-729: Path normalization silently handles consecutive slashes.

      parts.filter(Boolean) removes empty strings, normalizing paths like /foo//bar to /foo/bar. This is likely intentional for robustness, but callers might expect strict path validation instead of silent normalization.

      The current behavior is reasonable for a router.

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

    17. ✅ Actions performed

      Review triggered.

      Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

    18. Actionable comments posted: 0

      ♻️ Duplicate comments (4)
      packages/router-core/src/new-process-route-tree.ts (3)

      170-170: Critical: Fix depth calculation when reusing existing nodes.

      Lines 170, 185, 222, 260, and 288 use ++depth to set next.depth, which mutates the outer depth variable. When the loop encounters an existing child node, depth is incremented but never synchronized with the child's actual depth. This causes subsequent siblings to receive incorrect depth values, breaking buildBranch and extractParams for routes that share prefixes (e.g., /foo/bar followed by /foo/baz).

      Apply this diff to compute depth from the parent and resync for both new and existing nodes:

                 if (caseSensitive) {
                   const existingNode = node.static?.get(value)
                   if (existingNode) {
                     nextNode = existingNode
                   } else {
                     node.static ??= new Map()
                     const next = createStaticNode<TRouteLike>(
                       route.fullPath ?? route.from,
                     )
                     next.parent = node
      -              next.depth = ++depth
      +              next.depth = node.depth + 1
                     nextNode = next
                     node.static.set(value, next)
                   }
                 } else {
                   const name = value.toLowerCase()
                   const existingNode = node.staticInsensitive?.get(name)
                   if (existingNode) {
                     nextNode = existingNode
                   } else {
                     node.staticInsensitive ??= new Map()
                     const next = createStaticNode<TRouteLike>(
                       route.fullPath ?? route.from,
                     )
                     next.parent = node
      -              next.depth = ++depth
      +              next.depth = node.depth + 1
                     nextNode = next
                     node.staticInsensitive.set(name, next)
                   }
                 }

      Apply similar fixes to dynamic/optional/wildcard node creation:

                     )
                     nextNode = next
      -              next.depth = ++depth
      +              next.depth = node.depth + 1
                     next.parent = node

      And resync depth after advancing to the next node:

             node = nextNode
      +      depth = node.depth
           }

      Also applies to: 185-185, 222-222, 260-260, 288-288


      546-546: Critical: Pass caseSensitive parameter to parseSegments.

      Line 546 hardcodes caseSensitive as the first argument but then calls parseSegments(caseSensitive, ...). However, the temporary tree is always built with case-insensitive semantics because the hardcoded value should match the caller's caseSensitive parameter. Currently, static segments are lowercased regardless of the caller's flag, breaking router.matchRoute({ caseSensitive: true }).

      The code currently passes caseSensitive correctly on line 546. If tests are failing, verify the logic inside parseSegments properly honors the flag.


      895-898: Critical: Fix wildcard suffix validation to use the correct segment.

      Lines 895-898 check the suffix for wildcards, but line 896 constructs end from parts.slice(index).join('/') which represents the rest of the path, not the current segment. For wildcards in the middle of a path, this reads the wrong portion and breaks suffix matching.

      Apply this diff:

                 if (suffix) {
      -            const end = parts.slice(index).join('/').slice(-suffix.length)
      -            const casePart = segment.caseSensitive ? end : end.toLowerCase()
      -            if (casePart !== suffix) continue
      +            const lastPart = parts[parts.length - 1]!
      +            const casePart = segment.caseSensitive ? lastPart : lastPart.toLowerCase()
      +            if (!casePart.endsWith(suffix)) continue
                 }
      packages/router-core/src/path.ts (1)

      194-201: Fix undefined prefix/suffix in optional param serialization.

      Line 200 uses template literals with prefix and suffix variables that may be undefined. When either is undefined, the resulting string will contain the literal text "undefined", corrupting the path template (e.g., "undefined{-$id}undefined").

      Apply this diff to normalize undefined values to empty strings:

           } else {
             // SEGMENT_TYPE_OPTIONAL_PARAM
      -      joined += `${prefix}{-$${value}}${suffix}`
      +      const safePrefix = prefix ?? ''
      +      const safeSuffix = suffix ?? ''
      +      joined += `${safePrefix}{-$${value}}${safeSuffix}`
           }
      🧹 Nitpick comments (5)
      packages/router-core/src/new-process-route-tree.ts (1)

      311-328: Consider adding alphabetical fallback to sortDynamic.

      The sortDynamic function prioritizes prefix/suffix length but doesn't provide a stable fallback when segments are identical. This can lead to non-deterministic ordering across environments or V8 versions.

      Add a final alphabetical comparison:

         if (a.suffix && !b.suffix) return -1
         if (!a.suffix && b.suffix) return 1
      +  // Fallback to alphabetical order for stability
      +  const aStr = (a.prefix ?? '') + (a.suffix ?? '')
      +  const bStr = (b.prefix ?? '') + (b.suffix ?? '')
      +  return aStr.localeCompare(bStr)
      -  return 0
       }
      packages/router-core/tests/optional-path-params-clean.test.ts (1)

      3-10: Fix import order and type import style.

      Lines 7 and 9 violate ESLint rules for import ordering and type import style. These are minor style issues but should be fixed for consistency.

      Apply this diff:

       import {
         findSingleMatch,
         parseSegment,
         processRouteTree,
      -  SEGMENT_TYPE_OPTIONAL_PARAM,
         SEGMENT_TYPE_PATHNAME,
      -  type SegmentKind,
      +  SEGMENT_TYPE_OPTIONAL_PARAM,
       } from '../src/new-process-route-tree'
      +import type { SegmentKind } from '../src/new-process-route-tree'
      packages/router-core/tests/new-process-route-tree.test.ts (1)

      4-4: Remove unused import or implement processFlatRouteList tests.

      Line 4 imports processFlatRouteList but it's only used in a describe.todo block (lines 317-329). Either implement the tests or remove the import to clean up the code.

      If tests aren't ready, remove the import:

       import {
         findRouteMatch,
      -  processFlatRouteList,
         processRouteTree,
       } from '../src/new-process-route-tree'

      Also applies to: 317-329

      packages/router-core/tests/path.test.ts (1)

      9-18: Fix import issues: remove unused import and fix style.

      Line 13 imports SEGMENT_TYPE_OPTIONAL_PARAM but it's never used. Lines 13 and 17 also violate import ordering and type import style rules.

      Apply this diff:

       import {
         findSingleMatch,
         parseSegment,
         processRouteTree,
      -  SEGMENT_TYPE_OPTIONAL_PARAM,
         SEGMENT_TYPE_PARAM,
         SEGMENT_TYPE_PATHNAME,
         SEGMENT_TYPE_WILDCARD,
      -  type SegmentKind,
       } from '../src/new-process-route-tree'
      +import type { SegmentKind } from '../src/new-process-route-tree'
      packages/router-core/tests/optional-path-params.test.ts (1)

      3-12: Fix import order and type import style.

      Lines 7 and 11 violate ESLint rules for import ordering and type import style, similar to other test files.

      Apply this diff:

       import {
         findSingleMatch,
         parseSegment,
         processRouteTree,
      -  SEGMENT_TYPE_OPTIONAL_PARAM,
         SEGMENT_TYPE_PARAM,
         SEGMENT_TYPE_PATHNAME,
         SEGMENT_TYPE_WILDCARD,
      -  type SegmentKind,
      +  SEGMENT_TYPE_OPTIONAL_PARAM,
       } from '../src/new-process-route-tree'
      +import type { SegmentKind } from '../src/new-process-route-tree'
      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 58baf3e8158874b96a05f0b8598881e35cd76124 and b8aead3f43c41bd624a076669bfcb132fed94adc.

      📒 Files selected for processing (10)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/router-core/src/path.ts (5 hunks)
      • packages/router-core/src/router.ts (10 hunks)
      • packages/router-core/tests/match-by-path.test.ts (1 hunks)
      • packages/router-core/tests/new-process-route-tree.test.ts (1 hunks)
      • packages/router-core/tests/optional-path-params-clean.test.ts (2 hunks)
      • packages/router-core/tests/optional-path-params.test.ts (5 hunks)
      • packages/router-core/tests/path.test.ts (17 hunks)
      • packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx (0 hunks)
      • packages/router-plugin/src/core/route-hmr-statement.ts (3 hunks)
      💤 Files with no reviewable changes (1)
      • packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx
      🧰 Additional context used
      📓 Path-based instructions (4)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      packages/router-core/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep framework-agnostic core router logic in packages/router-core/

      Files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Files:

      • packages/router-plugin/src/core/route-hmr-statement.ts
      packages/router-plugin/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Use unplugin for universal bundler plugins in the router-plugin package

      Files:

      • packages/router-plugin/src/core/route-hmr-statement.ts
      🧠 Learnings (12)
      📓 Common learnings
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      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-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-core/tests/optional-path-params-clean.test.ts
      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-10-14T18:59:33.990Z
      Learnt from: FatahChan
      Repo: TanStack/router PR: 5475
      File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
      Timestamp: 2025-10-14T18:59:33.990Z
      Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-core/** : Keep framework-agnostic core router logic in packages/router-core/

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-28T21:41:45.233Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.

      Applied to files:

      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.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-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/tests/match-by-path.test.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/router-plugin/** : Use unplugin for universal bundler plugins in the router-plugin package

      Applied to files:

      • packages/router-plugin/src/core/route-hmr-statement.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-cli,router-generator,router-plugin,virtual-file-routes}/** : Keep CLI, generators, bundler plugins, and virtual file routing utilities in their dedicated tooling package directories

      Applied to files:

      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/router.ts
      • packages/router-core/tests/new-process-route-tree.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-09-23T17:36:12.598Z
      Learnt from: CR
      Repo: TanStack/router PR: 0
      File: AGENTS.md:0-0
      Timestamp: 2025-09-23T17:36:12.598Z
      Learning: Applies to packages/{router-devtools,*-router-devtools}/** : Keep router devtools packages in packages/router-devtools/ and packages/*-router-devtools/

      Applied to files:

      • packages/router-plugin/src/core/route-hmr-statement.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/tests/path.test.ts
      🪛 ESLint
      packages/router-core/tests/optional-path-params-clean.test.ts

      [error] 7-7: Member 'SEGMENT_TYPE_OPTIONAL_PARAM' of the import declaration should be sorted alphabetically.

      (sort-imports)


      [error] 9-9: Prefer using a top-level type-only import instead of inline type specifiers.

      (import/consistent-type-specifier-style)

      packages/router-core/tests/optional-path-params.test.ts

      [error] 7-7: Member 'SEGMENT_TYPE_OPTIONAL_PARAM' of the import declaration should be sorted alphabetically.

      (sort-imports)


      [error] 11-11: Prefer using a top-level type-only import instead of inline type specifiers.

      (import/consistent-type-specifier-style)

      packages/router-core/tests/new-process-route-tree.test.ts

      [error] 4-4: 'processFlatRouteList' is defined but never used.

      (unused-imports/no-unused-imports)

      packages/router-core/tests/path.test.ts

      [error] 13-13: Member 'SEGMENT_TYPE_OPTIONAL_PARAM' of the import declaration should be sorted alphabetically.

      (sort-imports)


      [error] 13-13: 'SEGMENT_TYPE_OPTIONAL_PARAM' is defined but never used.

      (unused-imports/no-unused-imports)


      [error] 17-17: Prefer using a top-level type-only import instead of inline type specifiers.

      (import/consistent-type-specifier-style)

      🪛 GitHub Actions: pr
      packages/router-core/tests/match-by-path.test.ts

      [error] 42-42: Multiple test failures reported in match-by-path tests: expected undefined vs {} or mismatched shape in various matchByPath assertions.

      packages/router-core/src/router.ts

      [warning] 2094-2097: Unused eslint-disable directive (no problems were reported from '@typescript-eslint/require-await'); Async arrow function has no 'await' expression (require-await).

      🔇 Additional comments (17)
      packages/router-core/src/new-process-route-tree.ts (1)

      502-502: Verify depth initialization consistency across processing functions.

      Line 502 initializes depth at 0 when calling parseSegments, which is consistent with processRouteTree (line 596). Confirm this is correct for flat route lists and that buildBranch works as expected when mixing flat and tree routes.

      If depth 0 is correct for the root, this is fine. Otherwise, verify against tests.

      packages/router-plugin/src/core/route-hmr-statement.ts (1)

      25-28: Document limitation: HMR does not handle new route additions.

      The TODO on line 27 indicates that adding a new route requires rebuilding the entire tree, which the current HMR logic doesn't support. This means HMR will only work for updates to existing routes, not for adding/removing routes from the tree.

      Consider documenting this limitation in a comment or the PR description so users are aware that adding new routes during development will require a full reload.

      packages/router-core/src/path.ts (1)

      233-350: Impressive refactor: cursor-based interpolation is much cleaner.

      The new cursor-based approach to path interpolation is a significant improvement over the old implementation. It's more direct, easier to follow, and handles all segment types (pathname, param, wildcard, optional) in a unified way. The elimination of the intermediate segment array and direct string assembly should also improve performance.

      packages/router-core/tests/match-by-path.test.ts (1)

      12-24: Fix matchByPath wrapper to return undefined for non-matches.

      The wrapper returns match ? match.params : undefined (line 23), but then line 24 is missing in the displayed code. Based on the pipeline failures expecting undefined but receiving {}, verify that the wrapper correctly returns undefined for non-matching paths rather than defaulting to an empty object.

      Ensure the logic matches test expectations:

      const matchByPath = (
        from: string,
        options: { to: string; caseSensitive?: boolean; fuzzy?: boolean },
      ) => {
        const match = findSingleMatch(
          options.to,
          options.caseSensitive ?? false,
          options.fuzzy ?? false,
          from,
          processedTree,
        )
        return match ? match.params : undefined  // Don't default to {}
      }
      ⛔ Skipped due to learnings
      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.
      Learnt from: FatahChan
      Repo: TanStack/router PR: 5475
      File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
      Timestamp: 2025-10-14T18:59:33.990Z
      Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.
      packages/router-core/src/router.ts (13)

      12-17: LGTM: Import changes align with the new route-tree architecture.

      The new imports from ./new-process-route-tree provide the necessary utilities for the processedTree-based matching pipeline.


      25-25: LGTM: LRU cache import supports performance optimization.

      This import enables the caching mechanism for path resolution mentioned in the PR benchmarks (~2.7× faster resolvePath).


      38-38: LGTM: Type import necessary for the new architecture.


      698-702: Simplified signature aligns with the new architecture.

      The GetMatchRoutesFn signature now accepts only a pathname and returns a complete match result object. This simplification is appropriate given that the processedTree encapsulates the matching logic.


      905-905: Verify the any type parameters in ProcessedTree.

      The ProcessedTree<TRouteTree, any, any> uses any for two generic parameters. Please ensure these cannot be more specifically typed for better type safety, or confirm that any is intentional for this context.

      Based on coding guidelines for TypeScript strict mode.


      1097-1109: LGTM: buildRouteTree correctly migrates to processedTree architecture.

      The method now properly destructures the new return value from processRouteTree and stores the processedTree on the router instance.


      1207-1208: LGTM: LRU cache initialization for path resolution performance.

      A cache size of 1000 entries is reasonable and aligns with the PR's performance improvements (~2.7× faster resolvePath).


      1215-1215: LGTM: Cache correctly threaded through to resolvePath.


      1540-1546: LGTM: getMatchedRoutes simplified to delegate to the new matching logic.

      The method now correctly passes processedTree to the standalone helper function and accepts only the pathname parameter.


      1607-1607: LGTM: Correctly uses the new getMatchedRoutes signature.


      1777-1793: Route masking correctly migrated to findFlatMatch.

      The masking logic now uses findFlatMatch with the processedTree. The flow properly extracts params and route properties from the match result.


      2503-2528: matchRoute correctly uses findSingleMatch with processedTree.

      The method now delegates to findSingleMatch and properly accesses the params property from the returned match. The logic for parameter and search comparison is preserved.


      2621-2651: The review comment's premise is incorrect.

      The third parameter to findRouteMatch is fuzzy (controls fuzzy/partial matching), not caseSensitive. Case sensitivity is already handled during route tree construction via processRouteTree(routeTree, this.options.caseSensitive, ...) at router initialization (line 1099). The processedTree passed to getMatchedRoutes already encodes case sensitivity rules from route definitions, so findRouteMatch does not need a separate caseSensitive parameter.

      Likely an incorrect or invalid review comment.

    19. ✅ Actions performed

      Review triggered.

      Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

    20. Actionable comments posted: 0

      🧹 Nitpick comments (1)
      packages/router-core/src/path.ts (1)

      129-129: Unusual cache key separator—confirm this is intentional.

      The cache key uses \\\\ as a separator between base and to paths. While this avoids conflicts with forward slashes, it's unconventional. If this choice was deliberate to prevent edge-case collisions, consider adding a brief inline comment explaining the rationale.

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 8df17ca79ddbf0f2047d21b518b60373bb000114 and bf328f36b0e3275da9fd34dc168e47e9da61ca91.

      📒 Files selected for processing (1)
      • packages/router-core/src/path.ts (4 hunks)
      🧰 Additional context used
      🧠 Learnings (7)
      📓 Common learnings
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      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.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      📚 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-core/src/path.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/src/path.ts
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/router-core/src/path.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/src/path.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-core/src/path.ts
      📚 Learning: 2025-09-28T21:41:45.233Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.

      Applied to files:

      • packages/router-core/src/path.ts
      🧬 Code graph analysis (1)
      packages/router-core/src/path.ts (4)
      packages/router-core/src/lru-cache.ts (1)
      • LRUCache (1-5)
      packages/router-core/src/utils.ts (1)
      • last (191-193)
      packages/router-core/src/new-process-route-tree.ts (6)
      • parseSegment (32-128)
      • SegmentKind (11-15)
      • SEGMENT_TYPE_PATHNAME (6-6)
      • SEGMENT_TYPE_PARAM (7-7)
      • SEGMENT_TYPE_WILDCARD (8-8)
      • SEGMENT_TYPE_OPTIONAL_PARAM (9-9)
      packages/router-generator/src/utils.ts (1)
      • cleanPath (38-41)
      ⏰ 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 (3)
      packages/router-core/src/path.ts (3)

      316-316: The 'undefined' string fallback is intentional and tested behavior.

      Tests in packages/router-core/tests/path.test.ts explicitly verify that missing required parameters produce the literal string 'undefined' (lines 279–289). The interpolation also correctly sets isMissingParams = true to signal incomplete paths.

      For comparison, optional parameters fall back to empty string, and splat parameters omit the segment entirely when missing. This design allows graceful degradation while flagging via isMissingParams that the path is incomplete.

      The current behavior appears intentional and working as designed. However, verify whether this is the intended design for the PR or if a different approach (throwing errors or omitting segments) is preferred for required parameters.


      117-207: Verify test status with actual test execution before merge.

      Tests for URL param encoding exist in packages/router-core/tests/path.test.ts (including URI component encoding cases with encodeURIComponent and custom decodeCharMap handling). However, I cannot execute the test suite to confirm whether tests are currently passing or if any are actually failing.

      Run the unit tests locally to verify the status of URL param encoding tests:

      pnpm run test:unit

      Ensure all path-related tests pass before merging, particularly the URI encoding tests in the interpolatePath describe block.


      194-201: The reported serialization issue does not exist—code is functioning correctly.

      Analysis of the code at lines 194-201 confirms:

      • prefix and suffix derive from substring() calls (lines 192-193), which always return strings, never undefined
      • The optional-param template literal ${prefix}{-$${value}}${suffix} produces exactly one $ character before the interpolated value: the {-$ contains a literal $ (not interpolation), followed by ${value} interpolation, creating {-$value} at runtime—not double-$ or "undefined" artifacts
      • Test coverage confirms correct behavior across all scenarios (100+ tests in optional-path-params.test.ts, curly-params-smoke.test.ts, and others show expected output without corruption)

      No fixes needed.

      Likely an incorrect or invalid review comment.

    21. Sheraff(GitHub profile, opens in a new tab) added labelsperformance

    22. Actionable comments posted: 2

      Caution

      Some comments are outside the diff and can’t be posted inline due to platform limitations.

      ⚠️ Outside diff range comments (2)
      packages/router-core/src/path.ts (1)

      105-205: resolvePath drops trailing slash for wildcard + empty _splat when trailingSlash: 'always'

      For a template like /splat/$ and trailingSlash: 'always', resolvePath currently:

      • Splits to ['', 'splat', '$', ''],
      • Appends '/' unconditionally when i > 0, even for the final empty segment,
      • Produces /splat//$, which cleanPath collapses to /splat/$.

      Later, when _splat is missing/empty, interpolatePath removes the wildcard segment and returns /splat with no trailing /, contradicting the expectation that 'always' yields /splat/ (see the new test in path.test.ts).

      You can fix this by making the join loop sensitive to leading/trailing empty segments instead of blindly inserting '/' for every index:

      -  let segment
      -  let joined = ''
      -  for (let i = 0; i < baseSegments.length; i++) {
      -    if (i > 0) joined += '/'
      -    const part = baseSegments[i]!
      -    if (!part) continue
      -    segment = parseSegment(part, 0, segment)
      -    const kind = segment[0]
      -    if (kind === SEGMENT_TYPE_PATHNAME) {
      -      joined += part
      -      continue
      -    }
      -    const end = segment[5]
      -    const prefix = part.substring(0, segment[1])
      -    const suffix = part.substring(segment[4], end)
      -    const value = part.substring(segment[2], segment[3])
      -    if (kind === SEGMENT_TYPE_PARAM) {
      -      joined += prefix || suffix ? `${prefix}{$${value}}${suffix}` : `$${value}`
      -    } else if (kind === SEGMENT_TYPE_WILDCARD) {
      -      joined += prefix || suffix ? `${prefix}{$}${suffix}` : '$'
      -    } else {
      -      // SEGMENT_TYPE_OPTIONAL_PARAM
      -      joined += `${prefix}{-$${value}}${suffix}`
      -    }
      -  }
      +  let segment
      +  let joined = ''
      +  for (let i = 0; i < baseSegments.length; i++) {
      +    const part = baseSegments[i]!
      +    const isFirst = i === 0
      +    const isLast = i === baseSegments.length - 1
      +
      +    if (!part) {
      +      // Leading empty segment -> ensure leading '/'
      +      if (isFirst && !joined) {
      +        joined = '/'
      +      } else if (
      +        isLast &&
      +        trailingSlash === 'always' &&
      +        !joined.endsWith('/')
      +      ) {
      +        // Trailing empty segment encodes the requested trailing slash
      +        joined += '/'
      +      }
      +      continue
      +    }
      +
      +    if (!isFirst && !joined.endsWith('/')) {
      +      joined += '/'
      +    }
      +
      +    segment = parseSegment(part, 0, segment)
      +    const kind = segment[0]
      +    if (kind === SEGMENT_TYPE_PATHNAME) {
      +      joined += part
      +      continue
      +    }
      +    const end = segment[5]
      +    const prefix = part.substring(0, segment[1])
      +    const suffix = part.substring(segment[4], end)
      +    const value = part.substring(segment[2], segment[3])
      +    if (kind === SEGMENT_TYPE_PARAM) {
      +      joined += prefix || suffix ? `${prefix}{$${value}}${suffix}` : `$${value}`
      +    } else if (kind === SEGMENT_TYPE_WILDCARD) {
      +      joined += prefix || suffix ? `${prefix}{$}${suffix}` : '$'
      +    } else {
      +      // SEGMENT_TYPE_OPTIONAL_PARAM
      +      joined += `${prefix}{-$${value}}${suffix}`
      +    }
      +  }

      This preserves existing behavior for static/param segments, but for templates like /splat/$ it yields /splat/$/, and after interpolation with _splat === '' the final path becomes /splat/ as intended.

      packages/router-core/src/router.ts (1)

      2478-2533: matchRoute ignores router-level caseSensitive option

      In the new implementation:

      const match = findSingleMatch(
        next.pathname,
        opts?.caseSensitive ?? false,
        opts?.fuzzy ?? false,
        baseLocation.pathname,
        this.processedTree,
      )

      caseSensitive defaults to false whenever the caller doesn’t pass it, even if the router was configured with caseSensitive: true. Previously, route matching (and therefore matchRoute) respected the router-level caseSensitive default.

      This can silently change behavior for apps that rely on case-sensitive routing but call matchRoute / useMatchRoute without explicitly specifying caseSensitive.

      A minimal fix is to fall back to the router option:

      -  const match = findSingleMatch(
      -    next.pathname,
      -    opts?.caseSensitive ?? false,
      -    opts?.fuzzy ?? false,
      -    baseLocation.pathname,
      -    this.processedTree,
      -  )
      +  const match = findSingleMatch(
      +    next.pathname,
      +    opts?.caseSensitive ?? this.options.caseSensitive ?? false,
      +    opts?.fuzzy ?? false,
      +    baseLocation.pathname,
      +    this.processedTree,
      +  )

      Everything else in matchRoute (deep-equality check for location.params, and optional search comparison) looks consistent with prior behavior.

      ♻️ Duplicate comments (1)
      packages/router-core/src/new-process-route-tree.ts (1)

      353-372: Add stable tie-breaker for deterministic route ordering.

      The sortDynamic function returns 0 when two segments have identical prefix, suffix, and case-sensitivity properties. This creates non-deterministic ordering when multiple routes share these attributes, which can cause inconsistent matching behavior across runs or JavaScript engines.

      Add a final alphabetical comparison by fullPath to ensure stable, deterministic ordering:

        if (a.suffix && !b.suffix) return -1
        if (!a.suffix && b.suffix) return 1
        if (a.caseSensitive && !b.caseSensitive) return -1
        if (!a.caseSensitive && b.caseSensitive) return 1
      + // Stable tie-breaker for deterministic ordering
      + return a.fullPath.localeCompare(b.fullPath)
      - return 0
      }
      🧹 Nitpick comments (2)
      packages/router-core/tests/optional-path-params-clean.test.ts (1)

      15-51: Shared parsePathname/PathSegment helpers could be centralized

      This PathSegment + parsePathname combo is effectively identical to the one in optional-path-params.test.ts. Consider extracting a tiny test utility (e.g. test-utils/segment-helpers.ts) to keep these helpers in sync and make future parser changes easier to roll out across tests.

      packages/router-core/src/new-process-route-tree.ts (1)

      510-522: Remove commented code before final merge.

      The commented-out intoRouteLike function should be removed if it's no longer needed, or uncommented and documented if it will be used.

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between bf328f36b0e3275da9fd34dc168e47e9da61ca91 and f952c876b1698cb13c16a2be358f1e8d7344f1ac.

      📒 Files selected for processing (7)
      • packages/router-core/src/new-process-route-tree.ts (1 hunks)
      • packages/router-core/src/path.ts (4 hunks)
      • packages/router-core/src/router.ts (10 hunks)
      • packages/router-core/tests/new-process-route-tree.test.ts (1 hunks)
      • packages/router-core/tests/optional-path-params-clean.test.ts (2 hunks)
      • packages/router-core/tests/optional-path-params.test.ts (5 hunks)
      • packages/router-core/tests/path.test.ts (18 hunks)
      🚧 Files skipped from review as they are similar to previous changes (1)
      • packages/router-core/tests/new-process-route-tree.test.ts
      🧰 Additional context used
      🧠 Learnings (8)
      📓 Common learnings
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.
      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-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-core/tests/path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      📚 Learning: 2025-09-22T00:56:49.237Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
      Timestamp: 2025-09-22T00:56:49.237Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-10-14T18:59:33.990Z
      Learnt from: FatahChan
      Repo: TanStack/router PR: 5475
      File: e2e/react-start/basic-prerendering/src/routes/redirect/$target/via-beforeLoad.tsx:8-0
      Timestamp: 2025-10-14T18:59:33.990Z
      Learning: In TanStack Router e2e test files, when a route parameter is validated at the route level (e.g., using zod in validateSearch or param validation), switch statements on that parameter do not require a default case, as the validation ensures only expected values will reach the switch.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      📚 Learning: 2025-09-28T21:41:45.233Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5284
      File: e2e/react-start/basic/server.js:50-0
      Timestamp: 2025-09-28T21:41:45.233Z
      Learning: In Express v5, catch-all routes must use named wildcards. Use `/*splat` to match everything except root path, or `/{*splat}` (with braces) to match including root path. The old `*` syntax is not allowed and will cause "Missing parameter name" errors. This breaking change requires explicit naming of wildcard parameters.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/tests/optional-path-params.test.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-09-22T00:56:53.426Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5182
      File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
      Timestamp: 2025-09-22T00:56:53.426Z
      Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

      Applied to files:

      • packages/router-core/tests/path.test.ts
      • packages/router-core/src/path.ts
      • packages/router-core/src/new-process-route-tree.ts
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/router-core/src/path.ts
      • packages/router-core/tests/optional-path-params-clean.test.ts
      • packages/router-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.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-core/src/new-process-route-tree.ts
      • packages/router-core/src/router.ts
      🧬 Code graph analysis (6)
      packages/router-core/tests/path.test.ts (2)
      packages/router-core/src/path.ts (2)
      • interpolatePath (247-349)
      • resolvePath (116-206)
      packages/router-core/src/new-process-route-tree.ts (7)
      • processRouteTree (645-702)
      • findSingleMatch (595-615)
      • SegmentKind (11-15)
      • parseSegment (54-151)
      • SEGMENT_TYPE_PATHNAME (6-6)
      • SEGMENT_TYPE_PARAM (7-7)
      • SEGMENT_TYPE_WILDCARD (8-8)
      packages/router-core/src/path.ts (4)
      packages/router-core/src/lru-cache.ts (1)
      • LRUCache (1-5)
      packages/router-core/src/utils.ts (1)
      • last (191-193)
      packages/router-core/src/new-process-route-tree.ts (5)
      • parseSegment (54-151)
      • SEGMENT_TYPE_PATHNAME (6-6)
      • SEGMENT_TYPE_PARAM (7-7)
      • SEGMENT_TYPE_WILDCARD (8-8)
      • SEGMENT_TYPE_OPTIONAL_PARAM (9-9)
      packages/router-generator/src/utils.ts (1)
      • cleanPath (38-41)
      packages/router-core/tests/optional-path-params.test.ts (1)
      packages/router-core/src/new-process-route-tree.ts (8)
      • SegmentKind (11-15)
      • parseSegment (54-151)
      • SEGMENT_TYPE_PATHNAME (6-6)
      • SEGMENT_TYPE_OPTIONAL_PARAM (9-9)
      • SEGMENT_TYPE_PARAM (7-7)
      • SEGMENT_TYPE_WILDCARD (8-8)
      • processRouteTree (645-702)
      • findSingleMatch (595-615)
      packages/router-core/tests/optional-path-params-clean.test.ts (1)
      packages/router-core/src/new-process-route-tree.ts (6)
      • SegmentKind (11-15)
      • parseSegment (54-151)
      • SEGMENT_TYPE_PATHNAME (6-6)
      • SEGMENT_TYPE_OPTIONAL_PARAM (9-9)
      • processRouteTree (645-702)
      • findSingleMatch (595-615)
      packages/router-core/src/new-process-route-tree.ts (2)
      packages/router-core/src/route.ts (3)
      • path (1551-1553)
      • RouteLike (1968-1979)
      • fullPath (1555-1557)
      packages/router-core/src/lru-cache.ts (2)
      • LRUCache (1-5)
      • createLRUCache (7-74)
      packages/router-core/src/router.ts (5)
      packages/router-core/src/new-process-route-tree.ts (7)
      • ProcessedTree (539-554)
      • processRouteTree (645-702)
      • processRouteMasks (556-573)
      • findFlatMatch (578-590)
      • findSingleMatch (595-615)
      • trimPathRight (637-639)
      • findRouteMatch (617-634)
      packages/router-core/src/lru-cache.ts (1)
      • createLRUCache (7-74)
      packages/router-core/src/route.ts (2)
      • path (1551-1553)
      • RouteMask (1466-1475)
      packages/router-core/src/path.ts (3)
      • resolvePath (116-206)
      • cleanPath (25-28)
      • trimPathRight (38-40)
      packages/router-core/src/utils.ts (1)
      • deepEqual (333-387)
      🔇 Additional comments (15)
      packages/router-core/tests/optional-path-params.test.ts (2)

      15-55: Local parsePathname correctly tracks parseSegment output

      The helper cleanly mirrors parseSegment’s index contract (type/value/prefix/suffix) and reuses the buffer, so these tests are exercising the new segment parser accurately without extra allocations. Looks good.


      334-354: matchPathname wrapper preserves legacy matchPathname behavior

      Wiring findSingleMatch(options.to, …, from, processedTree) is consistent with the new function’s (from, …, path) signature and the legacy { to }-based API. Returning undefined only when to is provided and no match is found also matches previous semantics.

      packages/router-core/tests/optional-path-params-clean.test.ts (1)

      141-161: matchPathname test harness is consistent with the new single-route matcher

      The helper correctly seeds a minimal processedTree and delegates matching to findSingleMatch, so these tests validate the new matcher rather than the old path helpers. No issues spotted.

      packages/router-core/tests/path.test.ts (1)

      362-395: Trailing-slash interpolation tests align with interpolatePath behavior

      These new cases around required vs optional params and trailing / give good coverage of the updated interpolation logic, including optional segments with and without values. They match the current implementation’s intent.

      packages/router-core/src/path.ts (1)

      221-347: interpolatePath + encodeParam logic looks sound

      The new cursor-based interpolation using parseSegment correctly distinguishes pathname, param, optional param, and wildcard segments, and:

      • Tracks usedParams and isMissingParams consistently (including the _splat missing cases the tests assert on),
      • Leaves / unencoded for _splat via encodeURI, while routing all other params through encodePathParam + decodeCharMap,
      • Handles optional params with prefix/suffix by omitting just the param when the value is null/undefined.

      Given the existing tests around numeric params, URI encoding, missing params, and optional segments, the behavior here matches expectations.

      packages/router-core/src/router.ts (4)

      1212-1221: resolvePathWithBase cache wiring is straightforward

      Using a dedicated resolvePathCache LRU and passing it into resolvePath is a nice way to avoid recomputing path resolutions. The cache key intentionally omits trailingSlash based on the assumption that a router instance uses a fixed trailingSlash option, which matches how this cache is used here.


      1453-1551: getMatchedRoutes integration with ProcessedTree looks correct

      RouterCore.getMatchedRoutes now delegates to the exported getMatchedRoutes helper with { pathname, routesById, processedTree }. The helper uses findRouteMatch(trimPathRight(pathname), processedTree, true) and falls back to the root route when no match is found, preserving the previous fuzzy-root semantics. Param propagation into routeParams via Object.assign also guards against mutating cached match objects.


      1782-1797: Route mask matching via findFlatMatch is well-structured

      Using findFlatMatch<RouteMask<TRouteTree>>(next.pathname, this.processedTree) and copying match.params into a fresh params object avoids mutating cached matches, and destructuring { from: _from, ...maskProps } to build maskedDest keeps the public from field out of the masked navigation options. Behavior-wise this aligns with the existing route-masking model.


      2626-2655: getMatchedRoutes helper correctly switches to findRouteMatch

      The exported getMatchedRoutes now uses findRouteMatch(trimPathRight(pathname), processedTree, true) instead of flat-route parsing, then walks parentRoute links to build matchedRoutes, defaulting to the root route when no match is found. This is a clean adaptation to the new ProcessedTree representation and matches the router’s existing fuzzy-not-found behavior.

      packages/router-core/src/new-process-route-tree.ts (6)

      1-151: Well-structured parsing foundation.

      The segment parsing logic is clean and efficient. The use of Uint16Array for parsed segment representation is a smart performance optimization, and the regex patterns correctly handle the braced parameter syntax. The parseSegment function properly handles all segment types with appropriate index boundary tracking.


      162-351: Solid recursive tree-building logic.

      The parseSegments function correctly handles tree construction with proper depth tracking, node reuse, and case sensitivity. The logic to distinguish between layout routes and index routes (lines 329-337) is well thought out, and the recursive child processing maintains correct parent-child relationships.


      405-455: Well-structured node creation with performance considerations.

      The node creation functions properly initialize all fields, and the comment about field ordering for engine optimization shows attention to performance details. The type structure using discriminated unions is clean and type-safe.


      556-702: Comprehensive tree processing with proper caching.

      The tree processing functions correctly handle both tree-based and flat route structures. The LRU caching strategy is well-applied, and the depth initialization is consistent throughout. The routesByPath logic that prioritizes index routes (line 679) is correct for handling ambiguous cases.


      724-801: Parameter extraction logic is well-structured.

      The extractParams and buildBranch functions correctly handle all segment types with proper decoding. The lazy initialization of nodeParts and the bitmask optimization for optional params show good attention to performance.

      The URL encoding complexities (matching encoded path parts against unencoded route prefixes/suffixes) are inherently challenging and likely the source of the failing tests mentioned in the PR objectives.


      803-1055: Sophisticated matching algorithm with correct priority handling.

      The stack-based matching approach efficiently explores all possible routes with proper priority ordering. The use of statics/dynamics/optionals counters to track match quality is elegant, and the bitmask optimization for skipped optional params is clever. The wildcard suffix check (line 919) correctly handles multi-segment remaining paths by joining and checking the trailing characters.

      This is a complex but well-designed algorithm that correctly implements the intended matching semantics.

      Resolvedby Sheraff(GitHub profile, opens in a new tab)
      Resolvedby Sheraff(GitHub profile, opens in a new tab)

Sign in to join this conversation.