feat(router-core): validate params while matching#5936

SeanCassiere · 2026-01-05T09:47:58Z

Add a JSDoc annotation for @experimental mentioned this can change. Maybe even a link to the docs RouteOptionsType reference page.
If you search the codebase we should have something similar to copy off of marked with @link.

coderabbitai · 2025-12-24T12:08:27Z

⚠️ Potential issue | 🟡 Minor
🧩 Analysis chain
🏁 Script executed:
# First, check the RouteLike interface definition and its options field rg -n "interface RouteLike" --type=ts packages/router-core/src/ # Then view the specific lines in route.ts to see the RouteLike definition sed -n '2003,2014p' packages/router-core/src/route.ts
Repository: TanStack/router
Length of output: 342
🏁 Script executed:
# Search for skipRouteOnParseError usage throughout the codebase rg -n "skipRouteOnParseError" --type=ts packages/router-core/src/ # Check where RouteLike is used in matching logic rg -n "RouteLike" --type=ts -A3 packages/router-core/src/ | head -100
Repository: TanStack/router
Length of output: 7940
🏁 Script executed:
# Look for test files related to skipRouteOnParseError find packages -name "*.test.ts" -o -name "*.spec.ts"| xargs rg -l "skipRouteOnParseError"2>/dev/null ||echo"No test files found with skipRouteOnParseError"# Check for any @experimental tags in the route.ts file grep -n "@experimental\|@alpha\|experimental" packages/router-core/src/route.ts | head -20
Repository: TanStack/router
Length of output: 216
🏁 Script executed:
# Check the route.ts file to see if there are other interfaces besides RouteLike# and understand the complete type hierarchy grep -n "interface.*Route\|type.*Route" packages/router-core/src/route.ts | head -30 # Look at the UpdatableRouteOptions interface mentioned in the review rg -n "UpdatableRouteOptions" --type=ts packages/router-core/src/route.ts -A20
Repository: TanStack/router
Length of output: 4834
🏁 Script executed:
# Check the test file to verify if tests exist head -50 packages/router-core/tests/skip-route-on-parse-error.test.ts # Check how parseSegments is called and what route object is passed rg -n "parseSegments" --type=ts packages/router-core/src/ -B2 -A2
Repository: TanStack/router
Length of output: 3893
🏁 Script executed:
# Check if there's a type declaration or wider options interface used elsewhere rg -n "route\.options\?" --type=ts packages/router-core/src/new-process-route-tree.ts -B2 -A2 | head -50
Repository: TanStack/router
Length of output: 650
🏁 Script executed:
# Check if Route extends RouteLike or what the relationship is rg -n "class Route\|extends.*Route\|implements.*RouteLike" --type=ts packages/router-core/src/route.ts -A3 -B1 | head -40 # Check the full test file to see test coverage quality wc -l packages/router-core/tests/skip-route-on-parse-error.test.ts # Check how RouteLike is used - is it for serialization/export? rg -n "RouteLike" --type=ts packages/router-core/src/ -B2 -A2 | grep -E "export|JSON|serialize|toJSON"| head -20
Repository: TanStack/router
Length of output: 778
🏁 Script executed:
# Check the processRouteTree function to see what it accepts and returns rg -n "function processRouteTree\|export.*processRouteTree" --type=ts packages/router-core/src/ -A10
Repository: TanStack/router
Length of output: 41
🏁 Script executed:
# Get the processRouteTree function signature and implementation sed -n '755,790p' packages/router-core/src/new-process-route-tree.ts
Repository: TanStack/router
Length of output: 1590
🏁 Script executed:
# Check what the test file passes as tree parameter to processRouteTree grep -n "processRouteTree" packages/router-core/tests/skip-route-on-parse-error.test.ts -A5 | head -30
Repository: TanStack/router
Length of output: 1422
🏁 Script executed:
# Check Route class definition to understand relationship to RouteLike sed -n '586,650p' packages/router-core/src/route.ts
Repository: TanStack/router
Length of output: 1417
🏁 Script executed:
# Search for @experimental or @alpha markers in the entire file grep -n "@experimental\|@alpha\|experimental\|alpha" packages/router-core/src/route.ts
Repository: TanStack/router
Length of output: 41
🏁 Script executed:
# Check if @experimental/@alpha tags are used elsewhere in the codebase rg -n "@experimental|@alpha" --type=ts packages/router-core/src/ | head -20
Repository: TanStack/router
Length of output: 114
🏁 Script executed:
# Check Route vs RouteLike - see if they're related or separate concerns# Look at RouteOptions to see if it extends UpdatableRouteOptions rg -n "type RouteOptions\|interface RouteOptions" --type=ts packages/router-core/src/route.ts -A20 | head -40
Repository: TanStack/router
Length of output: 41
🏁 Script executed:
# Check the test more thoroughly - see if it's testing real routes or just mock objects tail -100 packages/router-core/tests/skip-route-on-parse-error.test.ts
Repository: TanStack/router
Length of output: 2824
Update RouteLike interface and add @experimental tag for type safety and consistency.
The type structure and documentation for skipRouteOnParseError are sound and well-implemented. However, two improvements are needed:
RouteLike interface compatibility: Update the RouteLike interface (lines 2011-2013) to expose skipRouteOnParseError in its options field:
options?: {caseSensitive?: boolean skipRouteOnParseError?: {params?: boolean priority?: number}}
Currently, the code accesses route.options?.skipRouteOnParseError (new-process-route-tree.ts:192, 389) but RouteLike only declares caseSensitive. The optional chaining masks this type mismatch.
Add @experimental tag: Add @experimental to the JSDoc for skipRouteOnParseError to match the pattern used elsewhere in the codebase (e.g., Matches.ts:90).
Comprehensive tests for this feature already exist in packages/router-core/tests/skip-route-on-parse-error.test.ts, covering successful parsing, error skipping with fallbacks, priority ordering, and edge cases.
🤖 Prompt for AI Agents
packages/router-core/src/route.ts around lines 1191-1217 and update RouteLike at lines ~2011-2013: expose skipRouteOnParseError in the RouteLike.options type and mark the JSDoc as @experimental; specifically, add skipRouteOnParseError?: { params?: boolean; priority?: number } to RouteLike.options so calls to route.options?.skipRouteOnParseError (new-process-route-tree.ts:192, 389) are type-safe, and add an @experimental tag to the existing JSDoc block for skipRouteOnParseError to match project conventions.

-Original file line number
+Diff line change
@@ Expand Up / @@ -1188,9 +1188,46 @@ export interface UpdatableRouteOptions< @@
  in out TBeforeLoadFn,
 > extends UpdatableStaticRouteOption,
  UpdatableRouteOptionsExtensions {
- // If true, this route will be matched as case-sensitive
+ /**
+ * Options to control route matching behavior with runtime code.
+ *
+ * @experimental 🚧 this feature is subject to change
+ *
+ * @link https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType
+ */
+ skipRouteOnParseError?: {
+ /**
+ * If `true`, skip this route during matching if `params.parse` fails.
+ *
+ * Without this option, a `/$param` route could match *any* value for `param`,
+ * and only later during the route lifecycle would `params.parse` run and potentially
+ * show the `errorComponent` if validation failed.
+ *
+ * With this option enabled, the route will only match if `params.parse` succeeds.
+ * If it fails, the router will continue trying to match other routes, potentially
+ * finding a different route that works, or ultimately showing the `notFoundComponent`.
+ *
+ * @default false
+ */
+ params?: boolean
+ /**
+ * In cases where multiple routes would need to run `params.parse` during matching
+ * to determine which route to pick, this priority number can be used as a tie-breaker
+ * for which route to try first. Higher number = higher priority.
+ *
+ * @default 0
+ */
+ priority?: number
+ }
+ /**
+ * If true, this route will be matched as case-sensitive
+ *
+ * @default false
+ */
  caseSensitive?: boolean
- // If true, this route will be forcefully wrapped in a suspense boundary
+ /**
+ * If true, this route will be forcefully wrapped in a suspense boundary
+ */
  wrapInSuspense?: boolean
  // The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up @@
 export type GetMatchRoutesFn = (pathname: string) => {
  matchedRoutes: ReadonlyArray<AnyRoute>
+ /** exhaustive params, still in their string form */
  routeParams: Record<string, string>
+ /** partial params, parsed from routeParams during matching */
+ parsedParams: Record<string, unknown> | undefined
  foundRoute: AnyRoute | undefined
+ parseError?: unknown
 }
 export type EmitFn = (routerEvent: RouterEvent) => void
@@ Expand DownExpand Up / @@ -1260,7 +1264,7 @@ export class RouterCore< @@
  opts?: MatchRoutesOpts,
  ): Array<AnyRouteMatch> {
  const matchedRoutesResult = this.getMatchedRoutes(next.pathname)
- const { foundRoute, routeParams } = matchedRoutesResult
+ const { foundRoute, routeParams, parsedParams } = matchedRoutesResult
  let { matchedRoutes } = matchedRoutesResult
  let isGlobalNotFound = false
@@ Expand DownExpand Up / @@ -1401,26 +1405,34 @@ export class RouterCore< @@
  let paramsError: unknown = undefined
  if (!existingMatch) {
- const strictParseParams =
- route.options.params?.parse ?? route.options.parseParams
- if (strictParseParams) {
- try {
- Object.assign(
- strictParams,
- strictParseParams(strictParams as Record<string, string>),
- )
- } catch (err: any) {
- if (isNotFound(err) || isRedirect(err)) {
- paramsError = err
- } else {
- paramsError = new PathParamError(err.message, {
- cause: err,
- })
+ if (route.options.skipRouteOnParseError) {
+ for (const key in usedParams) {
+ if (key in parsedParams!) {
+ strictParams[key] = parsedParams![key]
  }
+ }
+ } else {
+ const strictParseParams =
+ route.options.params?.parse ?? route.options.parseParams
- if (opts?.throwOnError) {
- throw paramsError
+ if (strictParseParams) {
+ try {
+ Object.assign(
+ strictParams,
+ strictParseParams(strictParams as Record<string, string>),
+ )
+ } catch (err: any) {
+ if (isNotFound(err) || isRedirect(err)) {
+ paramsError = err
+ } else {
+ paramsError = new PathParamError(err.message, {
+ cause: err,
+ })
+ }
+ if (opts?.throwOnError) {
+ throw paramsError
+ }
  }
  }
  }
@@ Expand DownExpand Up / @@ -1802,7 +1814,7 @@ export class RouterCore< @@
  this.processedTree,
  )
  if (match) {
- Object.assign(params, match.params) // Copy params, because they're cached
+ Object.assign(params, match.rawParams) // Copy params, because they're cached
  const {
  from: _from,
  params: maskParams,
@@ Expand DownExpand Up / @@ -2601,18 +2613,18 @@ export class RouterCore< @@
  }
  if (location.params) {
- if (!deepEqual(match.params, location.params, { partial: true })) {
+ if (!deepEqual(match.rawParams, location.params, { partial: true })) {
  return false
  }
  }
  if (opts?.includeSearch ?? true) {
  return deepEqual(baseLocation.search, next.search, { partial: true })
- ? match.params
+ ? match.rawParams
  : false
  }
- return match.params
+ return match.rawParams
  }
  ssr?: {
@@ Expand DownExpand Up @@
  const trimmedPath = trimPathRight(pathname)
  let foundRoute: TRouteLike | undefined = undefined
+ let parsedParams: Record<string, unknown> | undefined = undefined
  const match = findRouteMatch<TRouteLike>(trimmedPath, processedTree, true)
  if (match) {
  foundRoute = match.route
- Object.assign(routeParams, match.params) // Copy params, because they're cached
+ Object.assign(routeParams, match.rawParams) // Copy params, because they're cached
+ parsedParams = Object.assign({}, match.parsedParams)
  }
  const matchedRoutes = match?.branch || [routesById[rootRouteId]!]
- return { matchedRoutes, routeParams, foundRoute }
+ return { matchedRoutes, routeParams, foundRoute, parsedParams }
 }
 function applySearchMiddleware({
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -136,6 +136,6 @@ describe('curly params smoke tests', () => { @@
  }
  const processed = processRouteTree(tree)
  const res = findRouteMatch(nav, processed.processedTree)
- expect(res?.params).toEqual(params)
+ expect(res?.rawParams).toEqual(params)
  })
 })

-Original file line number
+Diff line change
@@ Expand Up / @@ -26,7 +26,7 @@ describe('default path matching', () => { @@
  ['/b', '/a', undefined],
  ])('static %s %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -37,7 +37,7 @@ describe('default path matching', () => { @@
  ['/a/1/b/2', '/a/$id/b/$id', { id: '2' }],
  ])('params %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it('params support more than alphanumeric characters', () => {
@@ Expand All / @@ -49,7 +49,7 @@ describe('default path matching', () => { @@
  '/a/@&é"\'(§è!çà)-_°^¨$*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{',
  processedTree,
  )
- expect(anyValueResult?.params).toEqual({
+ expect(anyValueResult?.rawParams).toEqual({
  id: '@&é"\'(§è!çà)-_°^¨$*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{',
  })
  // in the key: basically everything except / and % and $
@@ Expand All / @@ -60,7 +60,7 @@ describe('default path matching', () => { @@
  '/a/1',
  processedTree,
  )
- expect(anyKeyResult?.params).toEqual({
+ expect(anyKeyResult?.rawParams).toEqual({
  '@&é"\'(§è!çà)-_°^¨*€£`ù=+:;.,?~<>|î©#0123456789\\😀}{': '1',
  })
  })
@@ Expand All / @@ -77,7 +77,7 @@ describe('default path matching', () => { @@
  ['/a/1/b/2', '/a/{-$id}/b/{-$id}', { id: '2' }],
  ])('optional %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -87,7 +87,7 @@ describe('default path matching', () => { @@
  ['/a/b/c', '/a/$/foo', { _splat: 'b/c', '*': 'b/c' }],
  ])('wildcard %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
 })
@@ Expand All / @@ -106,7 +106,7 @@ describe('case insensitive path matching', () => { @@
  ['/', '/b', '/A', undefined],
  ])('static %s %s => %s', (base, path, pattern, result) => {
  const res = findSingleMatch(pattern, false, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -116,7 +116,7 @@ describe('case insensitive path matching', () => { @@
  ['/a/1/b/2', '/A/$id/B/$id', { id: '2' }],
  ])('params %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, false, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -133,7 +133,7 @@ describe('case insensitive path matching', () => { @@
  ['/a/1/b/2_', '/A/{-$id}/B/{-$id}', { id: '2_' }],
  ])('optional %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, false, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -143,7 +143,7 @@ describe('case insensitive path matching', () => { @@
  ['/a/b/c', '/A/$/foo', { _splat: 'b/c', '*': 'b/c' }],
  ])('wildcard %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, false, false, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
 })
@@ Expand All / @@ -167,7 +167,7 @@ describe('fuzzy path matching', () => { @@
  ['/', '/a', '/b', undefined],
  ])('static %s %s => %s', (base, path, pattern, result) => {
  const res = findSingleMatch(pattern, true, true, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -178,7 +178,7 @@ describe('fuzzy path matching', () => { @@
  ['/a/1/b/2/c', '/a/$id/b/$other', { id: '1', other: '2', '**': 'c' }],
  ])('params %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, true, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -193,7 +193,7 @@ describe('fuzzy path matching', () => { @@
  ['/a/1/b/2/c', '/a/{-$id}/b/{-$other}', { id: '1', other: '2', '**': 'c' }],
  ])('optional %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, true, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
  it.each([
@@ Expand All / @@ -203,6 +203,6 @@ describe('fuzzy path matching', () => { @@
  ['/a/b/c/d', '/a/$/foo', { _splat: 'b/c/d', '*': 'b/c/d' }],
  ])('wildcard %s => %s', (path, pattern, result) => {
  const res = findSingleMatch(pattern, true, true, path, processedTree)
- expect(res?.params).toEqual(result)
+ expect(res?.rawParams).toEqual(result)
  })
 })

Navigation Menu

Uh oh!

Uh oh!

feat(router-core): validate params while matching#5936

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

SeanCassiereJan 5, 2026

Uh oh!

coderabbitaiBotDec 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat(router-core): validate params while matching#5936

Uh oh!

feat(router-core): validate params while matching #5936

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

SeanCassiereJan 5, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitaiBotDec 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!