fix(routing): decode matched params with decodeURIComponent

[NathanDrake2406]

Summary

• Dynamic params captured by the route matcher are now decoded with decodeURIComponent, matching Next.js behavior
• %2F → /, %23 → #, %3F → ? in param values (pages, route handlers, metadata, useParams)
• Decode applies to both single dynamic params and individual catch-all array elements

Problem

Vinext's segment-safe normalization preserves encoded delimiters for correct route matching (so /files/a%2Fb matches /files/[name] instead of splitting on the encoded slash). However, the captured param values were returned undecoded: the trie would correctly match but return name = "a%2Fb" instead of name = "a/b".

Next.js applies decodeURIComponent at the route-matcher level:
https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/route-matcher.ts#L25-L27

This divergence affects every consumer of matched params: page components, generateMetadata, route handlers, and useParams.

Fix

Add decodeURIComponent wrappers at the two route matching entry points:

• trieMatch in packages/vinext/src/routing/route-trie.ts — used by the App Router and Pages Router trie-based matchers
• matchRoutePattern in packages/vinext/src/routing/route-pattern.ts — used for slot-specific param extraction, route handlers, and metadata routes

The decode helpers handle both string and string[] (catch-all) param values and gracefully preserve malformed percent escapes (the normalization layer already validates encoding in the strict request path).

Tests

Edge case	Coverage
%2F, %23, %3F in dynamic segment	Decoded without splitting segments
Catch-all and optional catch-all arrays	Each element individually decoded
Malformed %GG	Preserved without throwing
Double-encoded %252F	Single decode pass only (→ %2F)

Verification

• vp test run tests/route-trie.test.ts — 64 tests pass
• vp test run tests/route-pattern.test.ts — 9 tests pass
• vp test run tests/routing.test.ts tests/route-sorting.test.ts — 143 tests pass
• vp test run tests/app-router.test.ts — 300 tests pass
• vp test run tests/pages-router.test.ts — 200 tests pass
• vp lint — 0 warnings, 0 errors

References

• Next.js route-matcher.ts decode: https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/route-matcher.ts#L25-L27
• Next.js test for failed param decoding: https://github.com/vercel/next.js/blob/canary/test/production/pages-dir/production/test/index.test.ts#L1082

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/vinext@1049

commit: 3c18ddd

[Copilot]

Pull request overview

This PR aligns Vinext’s route matching behavior with Next.js by decoding captured dynamic route params at match time while preserving segment-safe matching. It updates both trie-based matching and pattern-based matching so page routes, route handlers, metadata routes, and related consumers all receive decoded param values consistently.

Changes:

• Decode matched dynamic params in trieMatch, including individual elements of catch-all arrays.
• Decode matched params in matchRoutePattern for slot extraction, route handlers, and metadata matching.
• Add focused regression tests covering encoded delimiters, catch-all params, malformed escapes, and single-pass decoding.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
packages/vinext/src/routing/route-trie.ts	Adds post-match param decoding for trie-based route matches and documents the behavior.
packages/vinext/src/routing/route-pattern.ts	Adds equivalent param decoding for pattern-based matching paths.
tests/route-trie.test.ts	Adds regression coverage for decoded trie params across dynamic and catch-all cases.
tests/route-pattern.test.ts	Adds regression coverage for decoded pattern-matched params.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[james-elicx]

/bigbonk review

[ask-bonk]

Clean, well-scoped fix. The decode placement at the two route-matching exit points (trieMatch and matchRoutePattern) is correct and mirrors the Next.js route-matcher.ts implementation. Test coverage is thorough — encoded delimiters, catch-all arrays, malformed escapes, and double-encoding are all covered.

I verified:

• All call sites of trieMatch (4) and matchRoutePattern (4, via wrappers) receive params that have been through normalizePathnameForRouteMatch[Strict], which decode-then-re-encodes path delimiters (%2F, %23, %3F, %5C). The new decodeURIComponent correctly finalizes decoding of those re-encoded delimiters. Non-delimiter characters are already decoded to literal UTF-8 at that point, so decodeURIComponent is a no-op on them — no double-decode risk for normal URLs.
• The strict normalization layer (app-rsc-request-normalization.ts:66-68) rejects malformed percent-encoding with a 400 before params ever reach the matcher, so the graceful try/catch fallback in decodeParam is defense-in-depth only (which is fine).
• matchConfigPattern in config-matchers.ts (the only other param extraction path) is intentionally not affected — those params are used for rewrite/redirect destination interpolation, not page component props.

Two minor suggestions below — neither is blocking.

[ask-bonk]

Nit: decodeParam / decodeParams in this file and decodePatternParam / decodePatternParams in route-pattern.ts are identical implementations. Consider extracting to a shared helper in routing/utils.ts (which already has decodeRouteSegment) to avoid the duplication. Something like:

// routing/utils.ts
export function decodeParamValue(value: string): string {
  try {
    return decodeURIComponent(value);
  } catch {
    return value;
  }
}

export function decodeMatchedParams<T extends Record<string, string | string[]>>(params: T): void {
  for (const key of Object.keys(params)) {
    const value = params[key];
    if (Array.isArray(value)) {
      params[key] = value.map(decodeParamValue) as T[string] & string[];
    } else {
      params[key] = decodeParamValue(value) as T[string] & string;
    }
  }
}

Non-blocking — the current approach is fine for two call sites.

[ask-bonk]

Worth noting: Next.js throws DecodeError (which bubbles to a 400 response) on malformed params, while this gracefully preserves the raw value. The test comment at route-trie.test.ts:478 explains the rationale well (the strict normalization layer already rejects malformed encoding). Might be worth adding a brief inline comment here too, since someone reading this file won't see the test comment:

Suggested change

	* Mirrors Next.js route-matcher.ts:25-27.
	* Mirrors Next.js route-matcher.ts:25-27. Next.js throws DecodeError on
	* malformed params; vinext's normalization layer rejects them earlier (400),
	* so this layer uses a silent fallback instead.

[ask-bonk]

Review submitted. Here's a summary of the review:

Approved with two non-blocking suggestions:

1. Code duplication — decodeParam/decodeParams in route-trie.ts and decodePatternParam/decodePatternParams in route-pattern.ts are identical. Suggested extracting to a shared helper in routing/utils.ts.

2. Inline doc improvement — The JSDoc on trieMatch could note the behavioral difference from Next.js (vinext silently preserves malformed params vs Next.js throwing DecodeError), since the rationale is currently only documented in the test file.

The fix itself is correct and well-placed. I traced all 8 call sites of trieMatch and matchRoutePattern and confirmed there's no double-decode risk for normal URLs — the upstream normalization decodes non-delimiter characters to literal UTF-8 (making decodeURIComponent a no-op on them) and re-encodes path delimiters which the new decode step correctly finalizes. The strict normalization layer rejects malformed encoding at the request boundary before params ever reach the matcher.

github run