refactor(router-core): improve interpolatePath performance by pre-compiling a single regex decoder

[Sheraff]

interpolatePath is in the hot path for most things (Link, navigation, preload, ...)

This PR adds a total of 8 lines of code (excluding comments) but significantly improves performance (by 0 to 70%) depending on the input string.

bench

@tanstack/router-core  new (decodeConfig) - interpolatePath: simple path
  1.77x faster than old (decodeCharMap)

@tanstack/router-core  new (decodeConfig) - interpolatePath: params with special characters
  1.53x faster than old (decodeCharMap)

@tanstack/router-core  new (decodeConfig) - interpolatePath: multiple params
  1.66x faster than old (decodeCharMap)

@tanstack/router-core  new (decodeConfig) - interpolatePath: complex params with many special chars
  1.61x faster than old (decodeCharMap)

@tanstack/router-core  old (decodeCharMap) - interpolatePath: curly brace params
  1.03x faster than new (decodeConfig)

@tanstack/router-core  old (decodeCharMap) - interpolatePath: optional params
  1.01x faster than new (decodeConfig)

@tanstack/router-core  old (decodeCharMap) - interpolatePath: splat/wildcard
  1.01x faster than new (decodeConfig)

@tanstack/router-core  new (decodeConfig) - interpolatePath: mixed complex path
  1.27x faster than old (decodeCharMap)

@tanstack/router-core  new (decodeConfig) - interpolatePath: aggregate all cases
  1.39x faster than old (decodeCharMap)

Summary by CodeRabbit

• Refactor
  • Improved path parameter handling with a more efficient internal mechanism, enhancing router performance and code maintainability.

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit d386732

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	9m 55s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 44s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-01-23 16:38:05 UTC

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors path parameter decoding across router-core from a Map-based approach (decodeCharMap) to a function-based decoder pattern. The new compileDecodeCharMap helper generates decoder functions, updating public API signatures in RouterCore, InterpolatePathOptions, and related call sites to propagate the decoder throughout the interpolation pipeline.

Changes

Cohort / File(s)	Summary
Core path interpolation refactoring packages/router-core/src/path.ts	Added compileDecodeCharMap() helper to build decoder functions from allowed characters. Replaced decodeCharMap?: Map<string, string> parameter with decoder?: (encoded: string) => string across encodeParam(), interpolatePath(), and encodePathParam(). Decoder now applied uniformly in parameter encoding for splat, named, and optional params.
Router core public API update packages/router-core/src/router.ts	Replaced public field pathParamsDecodeCharMap?: Map<string, string> with pathParamsDecoder?: (encoded: string) => string. Updated RouterCore.update() to compile decoder via compileDecodeCharMap(). Updated all interpolatePath() call sites to pass decoder instead of decodeCharMap.
Test updates packages/router-core/tests/path.test.ts	Updated test cases to use compileDecodeCharMap(['@', '+']) and pass decoder via decoder property in interpolatePath() options.
DevTools integration packages/router-devtools-core/src/BaseTanStackRouterDevtoolsPanel.tsx	Updated interpolatePath() call to use decoder: pathParamsDecoder instead of decodeCharMap: pathParamsDecodeCharMap.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• #5135 — Modifies path interpolation and decoding logic in the same core files, affecting how interpolatePath processes and returns parameters.
• #5851 — Alters interpolatePath options and signature along with router.ts path-building behavior.
• #5934 — Refactors optional-segment skipping logic within the same interpolatePath function.

Suggested labels

package: router-core, package: router-devtools-core, performance

Suggested reviewers

• schiller-manuel
• nlynzaad

Poem

🐰 A map once held the decoding cheer,
But functions now make paths so clear!
From characters compiled with care,
The decoder hops with data to spare.
Refactored paths, renewed and bright! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: refactoring interpolatePath to use a pre-compiled regex decoder instead of decodeCharMap for performance improvement.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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

[pkg-pr-new]

More templates

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

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: d386732