Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 133 ยท The Runtime

URLs, URLSearchParams and URLPattern

Learn the WHATWG URL class in Node.js, URLSearchParams, percent-encoding, building URLs safely, URL parsing pitfalls, the legacy url.parse and the global URLPattern for matching routes.

A URL looks like a simple string, and that is exactly why so many bugs hide in it. Is ?a=1&b=2 already part of the address or still to be added? Does + mean a space? Which characters need escaping, and in which part of the address? Building URLs with string concatenation works until the first user types an ampersand, a space or a non-English letter into a form.

Node.js implements the same WHATWG URL Standard as browsers. You get a URL class that parses an address into named pieces, a URLSearchParams class that edits the query string correctly, and, in Node 24, a global URLPattern class that matches addresses against patterns like /users/:id. All three are globals, so no import is needed. This lesson shows how to use them, which mistakes to avoid, and why the old url.parse() should stay in the past. The same classes power fetch in HTTP Clients and the router you will build in Building a Router from Scratch.

Anatomy of a URL

A URL is built from standard parts. The URL constructor parses them and exposes each one as a property.

Node.js Taking a URL apart

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.

Some details are worth memorising:

  • protocol includes the trailing colon (https:), search includes the leading ? and hash the leading #.
  • host is the host name plus the port when the port is not the default for the protocol; hostname is only the name; port is a string, empty for default ports.
  • origin is protocol, host name and port, with no user name or password. Two addresses are "same origin" when their origins match. That is the string browsers use for security decisions.
  • All properties are writable (except origin and searchParams), and setting one re-serialises href correctly.
Node.js Default ports and editing properties

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.

The default port is dropped when it matches the scheme, so https://example.com:443/a prints without :443. JSON.stringify(url) calls url.toJSON(), which returns the href; that makes URLs travel well inside JSON.

Relative URLs and the base argument

The constructor accepts a second argument, a base, against which a relative address is resolved. This is how links inside an HTML page work, and it is the right tool whenever you have only a path, such as the req.url of an incoming request.

Node.js Resolving relative URLs

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.

Without a base, a relative string is invalid and the constructor throws TypeError with the code ERR_INVALID_URL. For input that may be bad, you can use the static URL.canParse(input, base) (a check without exceptions) or URL.parse(input, base), which returns null instead of throwing. In an HTTP server you typically write new URL(req.url, 'http://localhost'): the base is a placeholder, because req.url is only the path and query.

Node.js canParse and parse

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.

example.com alone is not a URL because it has no scheme: the parser reads it as a relative path. Many validation bugs come from this, so check protocol after parsing if you only accept http: and https:.

URLSearchParams: the query string, done right

Each URL has a searchParams property, a live URLSearchParams object. Changing it updates url.search, and the reverse. You can also create one standalone from a string, an object or an array of pairs.

Node.js Reading and changing query parameters

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.

Remember these rules:

  • get returns the first value or null; getAll returns an array with every value.
  • set replaces all values of a key with one; append adds another value.
  • Every value is a string. Convert with Number() and validate.
  • Object.fromEntries(params) keeps only the last value of a repeated key. Use getAll or build arrays yourself when keys can repeat.
  • size (the number of entries) is available in recent Node versions.

Encoding rules and the plus sign

In the query part, a space is written as + and everything unsafe is percent-encoded as %XX using UTF-8. URLSearchParams does this for you, which is why you should never concatenate user text into a query string.

Node.js Building a query string safely

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.

The first example shows the damage: the unescaped & and = turned the query into the wrong parameters, so q became fish and the rest was lost (or turned into extra parameters). With searchParams.set, the round trip is exact. This is also the cure for injection through URLs: user text can never add a new parameter if it is encoded as a value.

Encoding functions and the other parts of a URL

JavaScript has two older global functions:

Function Leaves unescaped Use for
encodeURIComponent letters, digits, - _ . ! ~ * ' ( ) one piece: a path segment, a query value
encodeURI the above plus ; , / ? : @ & = + $ # a whole address that is already well-formed

They encode a space as %20, not +, and differ from URLSearchParams in a few characters. In practice: use URLSearchParams for query strings, encodeURIComponent for individual path segments, and avoid encodeURI in new code.

Node.js Encoding path segments

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.

Without encoding, the / created extra path segments and the # started a fragment, so the address pointed at the wrong resource. With encodeURIComponent the whole name stays one segment. Remember to decode the segment when you read it back. decodeURIComponent throws URIError on malformed sequences such as %E0%A4%A, so wrap it in try/catch when input is untrusted.

Parsing quirks you should know

The URL parser follows a long standard, which sometimes surprises people.

Node.js What the parser normalises

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.

You can see lower-casing of the scheme and host, removal of . and .. segments, internationalised host names converted to Punycode (xn--...), non-ASCII path characters percent-encoded, spaces becoming %20, and an IPv4 address written in hexadecimal turned into its dotted form (0x7f.1 becomes 127.0.0.1). That last conversion matters for security: a filter that blocks the string 127.0.0.1 may not block http://0x7f.1/. When you defend against requests to internal addresses, always parse with URL first and inspect hostname after normalisation, never the raw text. We cover this kind of server-side request risk in Web Application Security.

A URL's origin check must compare parsed URLs, not strings. https://[email protected]/ starts with the text https://example.com but its hostname is evil.test, because example.com@ is the user-info part. Compare new URL(x).origin or hostname to the value you trust.

Node.js Why you compare hostname, not text

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.

The first column (a string test) wrongly accepts three of the four addresses; the second column (the parsed hostname) accepts only the real one.

The legacy url.parse (avoid it)

Before the WHATWG class existed, Node had url.parse() with a different, looser parser, plus url.format() and url.resolve(). They are deprecated in documentation, produce different results from browsers, and have had security bugs involving hostnames. Use new URL() in all new code. You will see the old API in older libraries, and it is helpful to recognise it:

NODE
import url from 'node:url';

const legacy = url.parse('https://example.com/a?x=1');   // avoid
console.log(legacy.query);                              // 'x=1' (a string)

const modern = new URL('https://example.com/a?x=1');    // use this
console.log(modern.searchParams.get('x'));              // '1'

The legacy url.parse accepts input the modern parser rejects, which has caused mismatches (for example one part of a system checks with one parser and another part fetches with the other). If you must support old code, convert at the edge and use URL internally. The node:url module also keeps useful helpers such as fileURLToPath and pathToFileURL, shown in The os and path Modules, and urlToHttpOptions.

The legacy API in detail, and how to migrate

You will meet url.parse and the querystring module in older code, so here is what they do and what replaces each call. Both still work in Node 24, but they are documented as legacy.

Node.js querystring and url.parse next to the modern API

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.

Migration table:

Legacy call Replace with
url.parse(str, true).query new URL(str, base).searchParams
url.parse(str).pathname / .hostname new URL(str, base).pathname / .hostname
url.format(obj) build with URL setters, then url.href
url.resolve(from, to) new URL(to, from).href
querystring.parse(s) new URLSearchParams(s) or Object.fromEntries(...)
querystring.stringify(o) new URLSearchParams(o).toString()

Three differences matter when you migrate. URL needs an absolute address, so for a request path such as /items?id=3 pass a base: new URL(req.url, 'http://localhost'). querystring.stringify encodes spaces as %20 while URLSearchParams uses +, so tests that compare strings may need updating (servers decode both). And URLSearchParams keeps repeated keys with getAll, whereas Object.fromEntries keeps only the last value of each key.

Node 24 also prints a DEP0169 deprecation warning to stderr the first time url.parse() runs (you may see it below the output), which is a hint that the call is on its way out.

URLPattern: matching addresses

Routing means asking "does this URL look like /users/42, and what is the 42?". People used to write regular expressions or install path-to-regexp. The web platform now has a standard for this, URLPattern, and Node 24 provides it as a global.

URLPattern is a global in Node 24, but it is a comparatively new API, so check its status in the Node documentation for the version you deploy. If you need to support older runtimes, use a small matcher of your own or a library.

You build a pattern either from a string or from an object with one pattern per URL component (protocol, hostname, pathname, search, ...). A component you omit matches anything. test() returns a boolean; exec() returns a result with named groups.

Node.js Matching paths with URLPattern

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 cheat sheet:

Pattern Meaning
:id a named group matching one segment (anything except /)
:id? optional group
:path+ / :path* one or more / zero or more segments
:ext(png|jpg) a group with a regular-expression constraint
* an unnamed wildcard group, numbered 0, 1, ... in the result
{...}? an optional grouping of literal text and groups

Be careful that patterns are anchored: the whole pathname must match, not part of it. And, unlike the string passed to test, a string pattern constructor takes a full URL pattern such as 'https://example.com/books/:id'; for most server code the object form with only pathname is simpler.

A tiny router built on URLPattern

Node.js A mini router with URLPattern

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.

Note the last line: the group value keeps the percent-encoding (a%20b) because patterns match the URL's serialised form, so decode with decodeURIComponent before using it. You can extend this idea with method checks (405 responses), middleware and route groups; that is the work of the router lesson.

Pitfalls checklist

  • Do not concatenate user input into URLs; use URLSearchParams and encodeURIComponent.
  • A string without a scheme (example.com) is not an absolute URL.
  • searchParams.get returns strings or null; validate and convert.
  • Validate the parsed protocol and hostname, not the raw text.
  • Reject javascript: and data: URLs if you display user-supplied links.
  • Do not use url.parse() for new code.
  • A fragment (#...) is never sent to the server, so req.url never contains it.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does new URL('/docs/intro') (no second argument) do?

    A relative address needs a base. Without one the constructor throws. URL.parse returns null instead, and URL.canParse returns false.
  2. 2. Which is the safest way to add a user-supplied value to a query string?

    searchParams.set percent-encodes the value, so characters like & and = cannot change the structure of the query.
  3. 3. After new URL('https://example.com:443/a'), what is url.port?

    The default port of the scheme is dropped by the parser, and port is always a string, so it is empty.
  4. 4. Why is input.startsWith('https://example.com') a bad origin check?

    The text before @ is user-info, so the real hostname is evil.test. Parse the URL and compare hostname or origin.
  5. 5. What does URLPattern({ pathname: '/users/:id' }).test('https://x.test/users/42/posts') return?

    Patterns are anchored to the whole component. :id matches one segment only, so the extra /posts prevents a match.

Summary

  • URL parses an address into protocol, host, port, pathname, search and hash; relative inputs need a base.
  • URL.canParse and URL.parse handle bad input without exceptions.
  • URLSearchParams reads and writes queries with correct encoding; values are strings and keys may repeat.
  • encodeURIComponent is for single path segments or values; never concatenate raw user text.
  • The parser normalises case, dots, Punycode and numeric hosts: validate the parsed hostname and protocol.
  • Avoid the legacy url.parse().
  • URLPattern (global in Node 24) matches and extracts named groups, the foundation of a router.

Next: Buffers