●Change8

Migrating to Remix route-pattern@0.22.0

Version route-pattern@0.22.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 5/29/2026

3
Breaking Changes
2
Migration Steps
5
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

createMatchercreateHrefRoutePattern.parseRoutePattern.pathname.tokensRoutePattern.toString

Breaking Changes

●Issue #1

The behavior of `matcher.match` has changed when path segments contain percent-encoded characters that represent path separators (like `%2F`). Previously, these might have been treated as path separators, leading to incorrect segment splitting. Now, encoded path separators within a segment are preserved as part of that segment.

✓Solution

If you relied on matching paths where a segment contained an encoded separator (e.g., matching 'docs%2Freadme.md' against a segment parameter), you must now ensure the input URL matches the expected structure without the separator being interpreted by the matcher.

●Issue #2

The behavior of `createHref` has changed for pathname parameters. Characters that could change URL structure (`/`, `?`, `#`, `%`, ``) are now strictly encoded in pathname parameters.

✓Solution

If you were passing values containing these structural characters in pathname parameters, the resulting href will now contain percent-encoded versions of those characters. Review usages where path segments contained characters like `/` or `?`.

●Issue #3

Hostname parameters in `createHref` are now strictly validated against structural URL characters.

✓Solution

If you attempt to create a URL using `createHref` where a hostname parameter contains structural characters (`.`, `@`, `:`, `/`, `?`, `#` for variables, or `@`, `:`, `/`, `?`, `#` for wildcards), it will now throw a `CreateHrefError` instead of encoding the character.

Migration Steps

  1. 1
    Review usages of `createHref` where pathname parameters contained structural characters (`/`, `?`, `#`, `%`, ``) and expect the output URL to be percent-encoded.
  2. 2
    Review usages of `createHref` where hostname parameters contained structural characters (`.`, `@`, `:`, `/`, `?`, `#`) and handle the potential `CreateHrefError` if such characters are present.

Release Summary

This release enhances URL matching consistency by normalizing percent-encoded path segments and tightens security/correctness by strictly encoding pathname parameters and validating hostname parameters in `createHref`.

Need More Details?

View the full release notes and all changes for Remix route-pattern@0.22.0.

View Full Changelog