Node.js Reference ยท path, os and url
The Node.js URLPattern class
Reference for URLPattern in Node.js: match URLs against patterns with named groups, wildcards and optional parts, and read captured values.
URLPattern is a global class that matches URLs against a pattern, much like a router does. A pattern describes the pathname (and optionally protocol, hostname, query and more) using named groups such as :id, wildcards *, optional parts {...}? and modifiers like ?, + and *.
Calling pattern.test(url) answers yes or no, and pattern.exec(url) returns the captured groups for every URL component. It follows the web platform standard, so the same patterns work in browsers that support it and in service workers. In Node.js it is a global in current versions (Node.js 24 LTS has it).
const pattern = new URLPattern({ pathname: "/users/:id" }); console.log(pattern.exec("http://localhost/users/42").pathname.groups.id);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new URLPattern(input?: string | URLPatternInit, baseURL?: string, options?: { ignoreCase?: boolean }) pattern.test(input?: string | URLPatternInit, baseURL?: string): boolean pattern.exec(input?: string | URLPatternInit, baseURL?: string): URLPatternResult | null
| Name | Description |
|---|---|
input |
A pattern string, or an object with any of protocol, username, password, hostname, port, pathname, search, hash and baseURL. Missing components match anything. |
baseURL |
Base for relative pattern strings or relative URLs. |
options.ignoreCase |
Case-insensitive matching (the default is case-sensitive). |
Returns: test() gives a boolean. exec() gives null on no match, or an object with inputs and one entry for each component (pathname, search, hostname, ...) holding { input, groups }.
Properties: read-only strings for each component pattern (pattern.pathname, pattern.protocol, ...) and hasRegExpGroups.
Errors: a TypeError is thrown when the pattern syntax is invalid.
Usage notes
- Unnamed groups are numbered. A wildcard
*appears ingroupsas"0","1"and so on. - A missing optional part is
undefinedingroups, as formonthin the second example. - Only the components you give are compared.
{ pathname: "/a" }matches any scheme, host and query. Addprotocolandhostnamefor strict routing. - Trailing slashes matter.
/books/:iddoes not match/books/7/; write/books/:id{/}?to allow both. - Matching is on the URL after normalization, so
%2Fand case in the host behave as the URL parser dictates. - Group values are percent-encoded text from the URL; decode with
decodeURIComponent()if needed. - Check availability on old runtimes. Node.js 22 and older do not expose it as a global.
- Compile patterns once and reuse them; constructing a pattern for every request is wasteful.
Related
URL,URLSearchParams,URL.canParse()- Lessons: The url module