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().
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
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
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
nullor throws for most garbage input; it returns something. That is the danger: validation based onurl.parse()can pass strings that a browser, a proxy orfetch()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 legacyhostnamefor allow-list checks or SSRF protection. url.resolve()is also legacy.new URL(to, from).hrefis the replacement and follows browser resolution rules.- The legacy
queryobject comes from thequerystringmodule, whose parsing rules differ in small ways fromURLSearchParams; see querystring module. - Node.js prints a runtime deprecation warning (
DEP0169) the first timeurl.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).querywithnew URL(s, base).searchParamsand theUrlfields with the matchingURLproperties.