rou3 0.10, 0.11 and 0.12 align the route pattern syntax with URLPattern and make the router, the compiled matchers and routeToRegExp match exactly the same paths. This guide combines the migration notes of all three releases, so every "Before" column shows 0.9 behavior and every "After" column shows 0.12 behavior. Changes that a later release undid or replaced are left out.
Each section names the release that made the change. The full notes are in the GitHub releases: v0.10.0, v0.11.0, v0.12.0.
- Checklist
- Lookup paths
- Wildcards
- Params
- Patterns that now throw
- Router API
- Types
- Compiler
routeToRegExpandregExpToRoute- Overlap and
routeNodeKeys - Runtime
Most apps need only the first few items:
- Look up routes with the raw, encoded pathname (
new URL(req.url).pathname). Don't decode it first. - Check every
*in your routes. It now spans segments:/admin/*matches/admin/a/b. Use:namefor exactly one segment. - Replace
params._with a named catch-all (/**:path→params.path) orparams["0"]. - Rename params that contain
-(:user-id→:userId). - Start your app once. Pattern syntax that used to be accepted with a surprising meaning now throws a
rou3:error ataddRoute, quoting the route. Fix each one using Patterns that now throw. - If you use
routeToRegExpas a guard, update snapshots and re-check: its output now matches exactly the paths the router matches. - Run on Node.js 20.19 or later.
0.12 (#231)
addRoute percent-encodes a pattern's literal text once, like URLPattern. Lookup paths are never decoded or encoded, so pass the pathname as it appears in the URL.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/café |
/caf%C3%A9 |
no match | match |
/café |
/café |
match | no match |
/a b |
/a%20b |
no match | match |
- Regex constraints are not encoded: write
:x(%C3%A9), not:x(é). routeToRegExp,routeNodeKeysand the compiled matchers use the encoded text too (routeToRegExp("/café")is^\/caf%C3%A9\/?$).- Param values are returned as they appear in the path (
/users/:idon/users/a%20bgives{ id: "a%20b" }), as in 0.9. Decode them in your handler if you need to.
Migrate: stop calling decodeURI() / decodeURIComponent() on the path before findRoute.
0.10 (#210)
Lookup ignores at most one trailing slash, like the non-strict defaults of Express, find-my-way and Hono.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/users/:id |
/users/123/ |
{ id: "123" } |
{ id: "123" } |
/users/:id |
/users/123// |
{ id: "123" } |
no match |
/about |
/about// |
match | no match |
/ |
// |
match | no match |
Migrate: to accept repeated trailing slashes, collapse them before lookup, e.g. path.replace(/\/{2,}$/, "/").
0.11 (#230), 0.12 (#232, #241)
A :name needs a value, and every segment a :name+, :name* or **:name takes needs one too (URLPattern's [^/]+(?:/[^/]+)*). Handlers no longer need to guard against "" for these params.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo/:bar/x |
/foo//x |
{ bar: "" } |
no match |
/a/:x* |
/a// |
{} |
no match |
/foo/:bar+ |
/foo/a//b |
{ bar: "a//b" } |
no match |
/foo/**:bar |
/foo//a |
{ bar: "/a" } |
no match |
/foo/:bar+ |
/foo/a/b/ |
{ bar: "a/b" } |
{ bar: "a/b" } (one trailing slash is still ignored) |
These paths now fall through to a less specific route, or to no match. *, **, :name(.*) and regex constraints may still take empty segments.
Migrate: to accept empty segments, use *, **, :name(.*), or a constraint that allows empty, such as :id(\d*).
0.12 (#246)
. and .. segments in a pattern (including %2e forms) are resolved when the route is added, the way new URL() resolves a path.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo/../bar |
/bar |
no match | match |
/foo/../bar |
/foo/../bar |
match | no match |
/\.\./bar |
/../bar |
no match | match (escaped dots stay literal) |
/:id/.. |
accepted | throws |
- A dot segment next to a param, catch-all or group throws.
removeRouteresolves dot segments too:removeRoute(router, "GET", "/docs/../api")removes/api.- Lookup paths are unchanged. They are resolved only with
normalize: true, which now drops a..that would go above the root (/x/../../foo→/foo, 0.10) and keeps the trailing slash after a trailing./..like WHATWG URL (/a//.→/a//, 0.12).
Migrate: escape the dots (\.\.) to match a literal .. segment.
0.12 (#240)
* used to match one segment ([^/]*). It is now URLPattern's * ((.*)) and matches across /, also inside a segment. A trailing /foo/* still matches /foo.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo/* |
/foo/a |
{ 0: "a" } |
{ 0: "a" } |
/foo/* |
/foo/a/b |
no match | { 0: "a/b" } |
/foo/* |
/foo/ |
{} |
{ 0: "" } |
/foo/* |
/foo |
{} |
{} |
/*/x |
/a/b/x |
no match | { 0: "a/b" } |
/*.png |
/a/b.png |
no match | { 0: "a/b" } |
/a/:x?/* |
/a/b |
{ 0: "b" } |
{ x: "b" } |
- Rules keyed by a trailing
*now apply at every depth:"/admin/*": { auth: false }covers/admin/a/b, not just/admin/a. - A
*before more of the route (/*/x) needs at least one segment, so it does not match/x. - On the same node,
**<*<**:nameinfindAllRoutesorder.
Migrate:
- To match exactly one segment, use
/users/:id(or/users/:id?to also match/users). For 0.9's exact behavior, use/users{/([^\x2f]*)}?. - Inside a segment, replace
*with([^\x2f]*):/*.pngbecomes/([^\x2f]*).png.
0.12 (#234)
A bare ** is an unnamed capture, as in URLPattern. It is keyed "0", "1", … together with * and unnamed (…) groups, in pattern order across the whole pattern.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo/** |
/foo/a/b |
{ _: "a/b" } |
{ 0: "a/b", _: "a/b" } |
/foo/** |
/foo |
{ _: "" } |
{} |
params._still works but is deprecated.- A
**that matches zero segments leaves its key out (it used to set_: ""). - Unnamed keys after a
**shift up, and so do keys after an optional group holding unnamed captures (a left-out group still uses up its numbers):/x{(\d+)}?/*on/x/bgives{ 1: "b" }. - In
routeToRegExpoutput, the**group is named_0,_1, … instead of_.
Migrate: name the capture (/foo/**:path → params.path), or read params["0"] ?? "".
0.10 (#216)
Segments after ** used to be silently dropped, so /a/**/b behaved like /a/**. They are now matched from the end of the path.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/**/_payload.json |
/blog/post/_payload.json |
{ _: "blog/post/_payload.json" } |
{ 0: "blog/post", _: "blog/post" } |
/a/**/b |
/a/x/y |
{ _: "x/y" } |
no match |
/a/:x+/b |
/a/x/y |
{ x: "x/y" } |
no match |
/**.md |
/a/b.md |
{ _: "a/b.md" } |
{ 0: "a/b" } |
/a/**/balso matches/a/b(**over zero segments).removeRoute(router, "GET", "/a/**/b")no longer removes/a/**.- On paths that a route with segments after a catch-all matches, matches are ranked from the last segment backwards (literal > regex param > param > catch-all). Routers without such routes rank as before.
Migrate: if you relied on the trailing segments being ignored, register /a/** instead.
0.12 (#242)
A written (.*) is the same as *, and :name(.*) is a * keyed by name. Both match across segments, as routeToRegExp already did.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo/(.*) |
/foo/a/b |
no match | { 0: "a/b" } |
/foo/:p(.*) |
/foo/a/b |
no match | { p: "a/b" } |
/foo/:p(.*) |
/foo/ |
no match | { p: "" } |
:p(.*)?,(.*)+and other modifiers on these groups throw, as they do on*.- Other constraints that can match
/((.+),(.*?),([^x]*)) still stay within one segment.
Migrate: for a single-segment value, use :p or :p([^\x2f]*).
0.10 (#216), 0.12 (#240, #242)
A route can hold only one of *, **, :x+, :x*, (.*) or :x(.*). A second one throws rou3: a route can have only one ....
| Pattern | 0.9 on the path | Write instead |
|---|---|---|
/**/**, /a/:x+/b/:y+ |
accepted | one catch-all |
/**/*.png |
{ _: "a/b.png" } on /a/b.png |
/**/:file.png |
/file-*-*.png |
{ 0: "a", 1: "b" } on /file-a-b.png |
/file-:a-*.png, or ([^\x2f]*) for one of them |
/*/x/*, /*/**, /*/:p+ |
accepted | a named :param for all but one |
Param names are [A-Za-z_]\w*, as in URLPattern. A -, { or } ends a name.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/api/:test-id |
/api/abc |
{ "test-id": "abc" } |
no match |
/api/:test-id |
/api/abc-id |
{ "test-id": "abc-id" } |
{ test: "abc" } |
/blog/:year-:month |
/blog/2024-05 |
{ "year-": "2024-0", month: "5" } |
{ year: "2024", month: "05" } |
/blog/:id{-:title}? |
/blog/1-hi |
{ "id-": "1-h", title: "i" } |
{ id: "1", title: "hi" } |
/:a{b}? |
/xb |
{ ab: "xb" } |
{ a: "x" } |
InferRouteParams reads names the same way, so the types change too.
Migrate: rename params that contain -, e.g. :test-id → :testId or :test_id.
0.11 (#230), 0.12 (#233, #236, #238)
As in URLPattern, a :name takes as little as it can, and a * or a regex constraint takes as much as it can. An optional :name? after a capture in the same segment is matched in place, so the capture before it takes what it can.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/:name.:ext |
/a.tar.gz |
{ name: "a.tar", ext: "gz" } |
{ name: "a", ext: "tar.gz" } |
/:a-:b |
/x-y-z |
{ "a-": "x-y-", b: "z" } |
{ a: "x", b: "y-z" } |
/:a(\d+):b? |
/12 |
{ a: "1", b: "2" } |
{ a: "12" } |
/*-:x? |
/-- |
{ 0: "", x: "-" } |
{ 0: "-" } |
- After plain text nothing changes:
pre-:x?matchespre-andpre-<value>. - Constrained and literal in-segment params rank above plain ones on the same node, whatever the registration order:
/f/:name.pngand/f/:name.:ext(png|jpg)both beat/f/:name.:exton/f/a.png. - These segments now match in time linear in their length (closes the ReDoS class of CVE-2024-45296).
Migrate: to keep the old split, constrain the capture: /:name.:ext(\w+) gives { name: "a.tar", ext: "gz" }, and /:a(\d):b? gives { a: "1", b: "2" }.
0.11 (#230)
A ? on a param that does not start its segment makes only that param optional, not the whole segment.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/a/pre-:x? |
/a/pre-b |
{ x: "b" } |
{ x: "b" } |
/a/pre-:x? |
/a/pre- |
no match | match (no x) |
/a/pre-:x? |
/a |
match | no match |
Migrate: to make the whole segment optional, write /a/{pre-:x}?.
0.11 (#228)
Outside a regex constraint, \x is a literal x, as in URLPattern. 0.9 kept the backslash in static segments, while routeToRegExp dropped it.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/foo\.bar |
/foo.bar |
no match | match |
/a\*b |
/a*b |
no match | match |
/a/\(:x |
/a/(1 |
no match | { x: "1" } |
\\ is a literal backslash. A \/ or a trailing \ throws.
Migrate: if a route really needs a backslash in the path, write \\.
0.11 (#226, #228), 0.12 (#245)
The router tests a constraint against one segment while routeToRegExp puts it inside a whole-path regex, so constructs that behave differently in the two now throw.
| Pattern | Problem | Write instead |
|---|---|---|
/:slug((?!admin)\w+) |
look-around | /:slug(\w+) plus a static /admin route (a static route always wins) |
/:x(^\d+$) |
anchor | /:x(\d+) (constraints already match the whole segment) |
/:x((a)) |
capturing group inside a constraint | /:x((?:a)) |
/a/(), /a/(?:a|b), /a/(?<n>x) |
empty or (? group |
/a/:x((?:a|b)), /a/:n(x) |
/:x([[a-z]--a]) |
-- / && in a class (URLPattern's v-flag set operations) |
escape them: [a\-\-z], [a\&\&b] |
Look-arounds have no direct replacement: register the excluded paths as their own routes, or check the value in your handler.
A regex group right after a {…} group that ends in a param is an unnamed capture next to the param, not the param's constraint. A pattern that starts with a {/…} group no longer gets an extra / in front.
| Pattern | Path | 0.9 | 0.12 |
|---|---|---|---|
/{:foo}(.*) |
/foobarbaz |
{ foo: "foobarbaz" } |
{ foo: "f", 0: "oobarbaz" } |
{/:a}?/b |
/b |
no match | {} |
{/:a}?/b |
/x/b |
no match | { a: "x" } |
{/:a}?/b |
//b |
{} |
no match |
/{:foo}?(…),/:foo{}(…)and/:foo{(x)}?change the same way. Write the constraint on the param instead:/:foo(.*).- A
{:name}?group that follows text and ends its segment is read as:name?:/a/*{:x}?is/a/*:x?. - Text right after a leading
{/…}?({/a}?b,{/:a}?.png) throws.
addRoute (and routeToRegExp) throw rou3: <what> (<route as written>) for syntax that 0.9 accepted with a surprising meaning, so these show up at startup. Besides the catch-all, constraint, dot-segment and group cases above:
| Pattern | 0.9 | Write instead |
|---|---|---|
/a/:x(\d+)+, /a/pre-:x+ |
dropped the constraint or prefix (/a/:x(\d+)+ matched /a/1/2 as { x: "1/2" }) |
+ / * only after a whole-segment :name (/a/:x+) |
/a/**?, /a/*+, /:x??, /p/**:x? |
accepted, with an unclear meaning | /p/:x* for an optional catch-all |
/foo? |
never matched (lookup paths have no query) | /foo\? for a literal ? |
/a**b |
read as two wildcards | /a*b, or /a\*\*b for literal stars |
/a/**:x.json, /a/**:x(\d+) |
param named "x.json" / "x(\d+)" |
a plain **:name as the whole last segment |
/:0, /:1st, /:café, /:id$ |
accepted as names | /:v1, /:_1, /:cafe, /:id\$ |
/a/:, /a/x: |
literal : |
/a/\: |
/a/:x/:x, /a/:x.:x |
later value won, or a raw SyntaxError |
unique names |
/files/:path/**:path, /a/:_/** |
duplicate name, raw SyntaxError in routeToRegExp |
unique names |
/a/{b, /a/b}, /a/{{b}} |
literal or mis-parsed braces | \{ / \} for literal braces, no nested groups |
/a/{b}+, /a{/b}* |
threw a non-rou3: error |
not supported (only {…} and {…}?) |
/a/(b (a ( that does not close in its segment) |
threw a raw SyntaxError |
close it, or escape it as \( |
/{:foo}{*}, /{:foo}?*, /{:foo}(x)?, /*{*} |
accepted | write the modifier or constraint on the param |
a raw tab, LF or CR ("/a\tb") |
accepted | %09, %0A, %0D (or \t, \n, \r inside a constraint) |
| U+FFFD–U+FFFF in a pattern | accepted | not allowed (used internally) |
See invalid patterns for the full list.
Method-agnostic routes are no longer hidden by method routes (0.11, #223). A route added with method "" could disappear when a route for a specific method landed on the same tree node, even if that route didn't match. Both are now always considered, and the more specific one wins. On a tie, the method route still wins.
addRoute(router, "", "/u/*", "any");
addRoute(router, "GET", "/u/:id(\\d+)", "get");
findRoute(router, "GET", "/u/abc"); // 0.9: undefined 0.12: "any"
findAllRoutes(router, "GET", "/u/42"); // 0.9: ["get"] 0.12: ["any", "get"]A "" middleware or auth route is no longer silently dropped from findAllRoutes (or compiled matchAll), and a more specific "" route now beats a broader method route.
removeRoute removes only the route you pass (0.10, #202). Removing /a/:id used to also remove /a/:userId, and removing /a/** also removed /a/**:rest. If you relied on that, call removeRoute once per registered pattern.
findAllRoutes lists each addRoute call once (0.12). /a/:x?/:y? on /a/b used to be returned twice ({ x } and { y }); it is now returned once, with the variant findRoute picks.
Results (0.11, #219):
findRouteandfindAllRoutesreturn a fresh{ data, params }object on every call. Static matches no longer expose internal fields (such asparamsRegexp), and mutating a result no longer affects later lookups.- Falsy route data (
0,false,"") is returned as-is instead ofnull. Missing data is stillnull.
RouterContext properties are marked @internal (0.12). Don't read or write the router's tree directly.
InferRouteParamstypes optional params (:id?,:id*) and a trailing whole-segment*,(.*)or:name(.*)asstring | undefined(0.10, #198; 0.12). Handleundefined, e.g.params.id ?? "".- Names are read like the router: constraints and modifiers are stripped (
:id(\d+)→id), and-ends a name (/blog/:year-:month→{ year, month }). - A bare
**key isstring | undefined, plus a deprecated_?: string.**<text>is one key. compileRouter<T>(router, { matchAll: true })is typed as returning an array (0.11).RouterCompilerOptionsis deprecated in favor ofCompileRouterToStringOptionsandCompileRouterOptions(0.11).
0.11 (#225)
compileRouterToString takes an options object: compileRouterToString(router, { functionName, matchAll, serialize }). The (router, "name", opts) form still works but is deprecated.
Route data in the generated code always goes through JSON.stringify, so the output is always valid code:
| Route data | 0.9 output | 0.12 output |
|---|---|---|
new Date(0) |
invalid code | "1970-01-01T00:00:00.000Z" |
{ toJSON: () => ({ a: 1 }) } |
invalid code | { a: 1 } |
{ toJSON: () => "code" } |
emitted code as raw JS |
the string "code" |
| a function, symbol or bigint (anywhere in the data) | silently dropped, or a raw TypeError |
throws a rou3: error |
Migrate: if your data contains functions or used toJSON() to emit code, pass serialize: (data) => "<js expression>".
routeToRegExp(p) now matches exactly the paths findRoute matches on a router holding only p, so it is safe to use as a guard. If you use it for scope or permission checks, upgrade.
/api/**no longer matches/apifoo(0.10).- Catch-alls match line terminators the way the router does (0.10). In 0.9,
/admin/**:pdidn't match/admin/x\ry, which the router routed. - Segments after
**are kept (0.10). - All the router changes above apply:
*spans segments, literal text is percent-encoded,:name+/:name*/**:nameuse[^/]+(?:/[^/]+)*, and**groups are named_0,_1, … instead of_. - The regex text changed for almost every route. Update snapshots and string comparisons. Most routes no longer use look-behind, so the regexes also compile in RE2, Go
regexpand Rustregex. Output for segments with several params no longer backtracks polynomially. - An empty required segment at the end (
/a/:xon/a//) used to leave its groupundefined; the route no longer matches at all. - On engines without duplicate named groups (Node 20 / 22), a group right before or after a trailing
*that can't be inlined throwsrou3: the regex for "…" repeats a named group…(/{b}?/*,/files/*{.:ext}?/raw).
regExpToRoute (0.11, #218; 0.12):
| Input | 0.9 | 0.12 |
|---|---|---|
/\/users\/(?<id>\d+)/ |
/users/:id(\d+) |
throws (unanchored) |
/^\/users/ |
/users |
throws (unanchored) |
/^\/a\/(?<x>\p{L}+)$/u |
/a/:x(\p{L}+) |
throws (u / v flag) |
/^\/users$/ |
/users |
/users |
- It reads regexes from older
routeToRegExpversions (old_groups included), except output for patterns that now throw, such as:x(\d+)+. Some routes come back in an equivalent form, e.g./a/:x?/:y?→/a{/:x/:y?}?, and an unnamed catch-all comes back as**. - It throws on a literal char that a route would encode, on a raw tab/LF/CR or
--/&&inside a constraint class, and on a hand-written trailing\/([^/]*)\/?$, which no route matches anymore.
Migrate: anchor hand-written regexes with ^…$ and drop the u / v flags.
findOverlappingRoutesreports a route with optional parts once, and reports distinct routes separately even when they share the same data object (0.11, #220).compareRoutes("/a/*", "/a/**")is"equal"(it was"subset"), since*is now a catch-all./a/:x*equals/a{/**:y}?and is a subset of/a/**(0.12).routeNodeKeys("/a/*")gives["/a/**"], and param segments are keyed:_0,:_1, … (0.12).
package.json declares "engines": { "node": ">=20.19.0" } (0.11, #224).