File an issue

node:url

Elide implements Node.js's url module on top of the same Servo [url][rs-url] and [idna][rs-idna] crates that back the WHATWG URL / URLSearchParams globals, so the legacy API's output stays consistent with the constructor's when they're used together.

[rs-url]: https://crates.io/crates/url [rs-idna]: https://crates.io/crates/idna

Import

js
import url from "node:url";                // or
const url = require("node:url");

Legacy API

url.parse(urlString, parseQueryString?, slashesDenoteHost?)

Parses urlString and returns a legacy UrlObject with protocol, slashes, auth, host, port, hostname, hash, search, query, pathname, path, and href fields. When parseQueryString is true, query is a plain object (duplicate keys collapse into arrays, per Node); otherwise it's a string.

url.format(urlObject)

Serialises a UrlObject or a WHATWG URL back to a string. For UrlObject, a non-empty href overrides the component fields; otherwise the pieces are assembled in the spec's order, handling missing : on protocol, missing ?/# prefixes on search/hash, and defaulting to authority form when slashes is true.

url.resolve(from, to) / url.resolveObject(from, to)

resolve returns the string form; resolveObject returns a UrlObject. Both use the WHATWG URL parser's base-relative resolution under the hood.

IDNA helpers

url.domainToASCII(domain)

Converts a Unicode domain to its Punycode/ASCII representation per UTS #46. Failures (unparseable domains) return the empty string, matching Node.

url.domainToUnicode(domain)

Inverse of domainToASCII — accepts Punycode or mixed input and returns the Unicode form. Never throws; partial failures yield the best-effort decoding.

File-URL conversion

url.fileURLToPath(url)

Accepts a file: URL string or a WHATWG URL instance and returns the filesystem path string. Throws TypeError if the URL is not a file: URL or if the decoded bytes aren't a valid path on the host platform.

url.pathToFileURL(path)

Converts an absolute filesystem path to a WHATWG URL with the file: scheme. Throws TypeError for relative paths.

HTTP request helper

url.urlToHttpOptions(url)

Projects a WHATWG URL into an options object suitable for http.request(...): { protocol, hostname, hash, search, pathname, path, href, port?, auth? }. port is omitted for default ports; auth is set only when username or password is non-empty.

Re-exports

  • url.URL — same value as the global URL.
  • url.URLSearchParams — same value as the global URLSearchParams.

Example

js
const url = require("node:url");

const parsed = url.parse("https:<<>>
parsed.host;             <<>>
parsed.query.x;          <<>>

url.format({
  protocol: "https:",
  hostname: "example.com",
  pathname: "/x",
  search: "?q=1",
});                      <<>>

url.resolve("https://example.com/a/b/c", "../x");
                         // "https://example.com/a/x"

url.domainToASCII("日本.jp");           // "xn--wgv71a.jp"
url.pathToFileURL("/tmp/foo").href;    // "file:///tmp/foo"

Compatibility notes

  • Legacy url.parse is retained for compatibility; new code should prefer the URL constructor.
  • All operations delegate to native Rust (url + idna), so behaviour matches Node.js, Deno, Servo, and reqwest.

See also