fix(router-core): use encodeURIComponent for splat route params #6520
Conversation
Use encodeURIComponent instead of encodeURI for splat route parameters to properly encode spaces, plus signs, and other special characters. This fixes an SSR redirect loop that occurs when: 1. User navigates to a splat route with encoded characters (e.g., %20) 2. TanStack Router decodes params with decodeURIComponent 3. When rebuilding URL, encodeURI doesn't encode spaces/special chars 4. URL mismatch triggers redirect loop (307 redirects) encodeURIComponent properly encodes these characters, preventing the mismatch while still preserving forward slashes as path separators.
📝 WalkthroughWalkthroughSplat params now early-return if the value is URL-safe; otherwise splat values are split on '/' and each segment is percent-encoded individually. The path-utils encoder was renamed to Changes
Sequence Diagram(s)(Skipped.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@thejasonxie thanks for this. I agree with the change to treat the various path segments for splat params similar to how path params is treated. encodePathParam uses encodeURIComponent underlying so made a change to rather use this and standardise across both path params and splat params. There were a few tests that failed, these were expected due to the change from encodeURI to encodeURIComponent and I updated those accordingly. |
|
just a quick note. this does not resolve #5031. The problem there was in fact that a space in a file-based route name results in a %20 i.e. |
|
View your CI Pipeline Execution ↗ for commit 2fe5668
☁️ Nx Cloud last updated this comment at |
|
The issue (#6519) and the added tests seem to imply that there is an issue with |
Add performance optimization that skips the split/map/join operation when splat values only contain URL-safe characters (alphanumeric, dash, period, underscore, tilde, exclamation, forward slash). This avoids unnecessary processing in the hot path for common cases.
Update encodeNonAscii to also encode whitespace characters (spaces, tabs, etc.) in addition to non-ASCII characters. This fixes SSR redirect loops where: 1. Request URL contains encoded spaces: /path/file%20name.pdf 2. parseLocation decodes pathname: /path/file name.pdf 3. buildLocation calls encodeNonAscii but spaces weren't encoded 4. URL mismatch triggers redirect loop Now encodeNonAscii properly encodes: - Whitespace characters (spaces become %20) - Non-ASCII/unicode characters (including emojis) Other ASCII special characters (parentheses, brackets, etc.) are preserved as they are valid in URL paths.
Yes, encodeNonAscii is part of the problem. Here's the flow that causes the SSR redirect loop:
I've added a second commit that updates encodeNonAscii to also encode whitespace characters. The fix:
Both fixes are needed:
|
|
Issue happens from accessing /file-name%20(3).pdf? in the url then refreshing which crashes Updated patch to fix my issue: diff --git a/node_modules/@tanstack/router-core/dist/esm/path.js b/node_modules/@tanstack/router-core/dist/esm/path.js
index 114353f..212f57d 100644
--- a/node_modules/@tanstack/router-core/dist/esm/path.js
+++ b/node_modules/@tanstack/router-core/dist/esm/path.js
@@ -121,7 +121,11 @@ function encodeParam(key, params, decoder) {
const value = params[key];
if (typeof value !== "string") return value;
if (key === "_splat") {
- return encodeURI(value);
+ // Early return if value only contains URL-safe characters (performance optimization)
+ if (/^[a-zA-Z0-9\-._~!/]*$/.test(value)) return value;
+ // Use encodeURIComponent for each segment to properly encode spaces and special characters
+ // but preserve forward slashes as path separators
+ return value.split('/').map(segment => encodeURIComponent(segment)).join('/');
} else {
return encodePathParam(value, decoder);
}
diff --git a/node_modules/@tanstack/router-core/dist/esm/utils.js b/node_modules/@tanstack/router-core/dist/esm/utils.js
index ebada3c..b5f5ca5 100644
--- a/node_modules/@tanstack/router-core/dist/esm/utils.js
+++ b/node_modules/@tanstack/router-core/dist/esm/utils.js
@@ -226,8 +226,10 @@ function decodePath(path, decodeIgnore) {
return result;
}
function encodeNonAscii(path) {
- if (!/[^\u0000-\u007F]/.test(path)) return path;
- return path.replace(/[^\u0000-\u007F]/gu, encodeURIComponent);
+ // Encode non-ASCII characters and whitespace that should be encoded in URLs
+ // eslint-disable-next-line no-control-
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ASCII range check
+ if (!/\s|[^\u0000-\u007F]/.test(path)) return path;
+ return path.replace(/\s|[^\u0000-\u007F]/gu, encodeURIComponent);
}
function buildDevStylesUrl(basepath, routeIds) {
const trimmedBasepath = basepath.replace(/^\/+|\/+$/g, "");
|
packages/router-core/src/utils.ts
Outdated
| return [...segment] | ||
| .map((char) => { | ||
| if (needsEncoding.test(char)) { | ||
| return encodeURIComponent(char) | ||
| } | ||
| return char | ||
| }) | ||
| .join('') |
There was a problem hiding this comment.
Why do we need char-by-char encoding? Can't we just return encodeURIComponent(segment)?
There was a problem hiding this comment.
encodeURIComponent encodes all characters except: A-Z a-z 0-9 - _ . ! ~ * ' ( )
This means it would encode characters like @, $, &, +, ,, ;, =, : which are valid in URL paths and were not being encoded before.
The function is named encodeNonAscii and its purpose is specifically to encode:
- Whitespace (spaces → %20, tabs → %09)
- Non-ASCII/Unicode (emojis, accented characters, etc.)
Using encodeURIComponent(segment) would be a breaking change - paths like /user@domain/file would become /user%40domain/file.
However, the char-by-char approach can be simplified. Instead of:
return [...segment]
.map((char) => needsEncoding.test(char) ? encodeURIComponent(char) : char)
.join('')We can use a regex replace:
return segment.replace(/\s|[^\u0000-\u007F]/gu, encodeURIComponent)There was a problem hiding this comment.
switched to regex
There was a problem hiding this comment.
Yeah I think that encodeNonAscii is poorly named, it's goal is to "encode like new URL would, but without requiring all the parsing that new URL does".
There was a problem hiding this comment.
Renamed it to encodePathLikeUrl and updated jsdoc
thejasonxie
force-pushed
the
fix/splat-route-encoding
branch
from
76bb322 to
8846a33
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@packages/router-core/src/utils.ts`:
- Around line 638-643: The regex using \u0000-\u007F triggers
lint/control-character errors; replace the regex-based detection/replace in
encodeNonAscii with an ASCII/whitespace scanner and segment-wise encoding:
implement a small loop that checks each character's charCodeAt(i) > 127 or
/\s/.test(char) to decide if encoding is needed, return the original path when
no encoding required, otherwise split path by '/' and map each segment to
encodeURIComponent(segment) only if that segment contains non-ASCII/whitespace
(using the same charCodeAt check), then join with '/'—update the encodeNonAscii
function to use these helpers instead of the problematic Unicode-range regex.
8846a33 to
885d008
Compare
thejasonxie
force-pushed
the
fix/splat-route-encoding
branch
from
885d008 to
bef5cb9
Compare
Rename the function to better reflect its expanded responsibility of encoding paths the same way new URL() would, including: - Whitespace characters (spaces → %20, tabs → %09) - Non-ASCII/Unicode characters (emojis, accented characters) The old name 'encodeNonAscii' was misleading since the function now encodes more than just non-ASCII characters.
3 participants
Summary
Fixes SSR redirect loop for splat routes with URL-encoded characters (spaces, plus signs, brackets, etc.)
Problem
When a splat route contains URL-encoded characters like
%20(space),%2B(plus), or%5B(bracket):/docs/file%20name.pdf_splatparam usingdecodeURIComponent→file name.pdfencodeURI()which doesn't encode spaces/docs/file name.pdfinstead of/docs/file%20name.pdfSolution
Changed
encodeParam()inpath.tsto useencodeURIComponentfor each path segment instead ofencodeURIon the entire splat value:// Before
return encodeURI(value)
// After
return value.split('/').map((segment) => encodeURIComponent(segment)).join('/')
This properly encodes spaces (%20), plus signs (%2B), brackets (%5B/%5D), and other special characters that encodeURI leaves unencoded, while still preserving forward slashes as path separators.
Changes
Testing
All 1030 existing tests pass, plus 18 new tests for special character encoding.
Resolves #6519
Summary by CodeRabbit
Bug Fixes
New Features
Tests
✏️ Tip: You can customize this high-level summary in your review settings.