Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท path, os and url

Node.js url.parse() (legacy) method

Reference for the deprecated legacy url.parse(), url.resolve() and url.format() object API in Node.js: the Url fields, its guessing rules, security risks and replacements.

url.parse() is the original Node.js URL parser, older than the WHATWG URL class. It turns a string into a plain Url object with fields such as protocol, host, pathname, search and query. It is still available, but it is documented as legacy, prints a runtime deprecation warning, and it should not be used for new code.

The reason is behavior, not age. The legacy parser does not follow the URL standard: it accepts strings a browser would reject, guesses where the host ends, and has a history of security bugs where it and a standards-compliant parser disagree about the same string. That disagreement is exactly what attackers use against allow-lists. Use new URL() or URL.parse().

NODE
import url from 'node:url';

const parsed = url.parse('https://[email protected]:8080/a/b?x=1#h', true);
console.log(parsed.hostname, parsed.query.x);

Try it

Node.js The Url object

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.

Node.js Same input, different parsers

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

NODE
url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
url.resolve(from, to)
url.format(urlObject)
Name Description
urlString The string to parse.
parseQueryString If true, query becomes an object (from the legacy querystring module, with a null prototype). Default false: query is the string without ?.
slashesDenoteHost If true, //foo/bar is read as host foo and path /bar. Default false.
from, to Base and target for resolve().

Returns: a Url object with protocol, slashes, auth, host, port, hostname, hash, search, query, pathname, path and href. Missing parts are null.

Errors: a non-string urlString throws ERR_INVALID_ARG_TYPE. Malformed input is usually accepted, not rejected.

Usage notes

  • It never returns null or throws for most garbage input; it returns something. That is the danger: validation based on url.parse() can pass strings that a browser, a proxy or fetch() read differently.
  • Hosts with illegal characters are handled differently from the WHATWG parser: the second example shows the legacy parser cutting a host at a space, where new URL() throws. Never use the legacy hostname for allow-list checks or SSRF protection.
  • url.resolve() is also legacy. new URL(to, from).href is the replacement and follows browser resolution rules.
  • The legacy query object comes from the querystring module, whose parsing rules differ in small ways from URLSearchParams; see querystring module.
  • Node.js prints a runtime deprecation warning (DEP0169) the first time url.parse() is called, saying its behavior is not standardized and that no CVEs are issued for it. The warning goes to stderr, as in both examples above.
  • It is still faster than new URL() in some microbenchmarks, which is the only common reason to keep it. Measure before accepting the risk.
  • To migrate, replace url.parse(s, true).query with new URL(s, base).searchParams and the Url fields with the matching URL properties.