Skip to content
Tutorials Center
My learning

Topics

Node.js Reference Β· path, os and url

The Node.js URL class

Reference for the URL class in Node.js: parse URLs, read and change parts, resolve relative links, handle errors and avoid common pitfalls.

URL is a global class that parses a URL string into its parts and lets you read or change each part. It follows the WHATWG URL Standard, the same rules browsers use, so a URL means the same thing in Node.js and in the browser.

You create one with new URL(input, base?). If the text is not a valid absolute URL (and no base can complete it), the constructor throws a TypeError with the code ERR_INVALID_URL. Every property, such as pathname or hostname, is a getter and setter that keeps the whole URL consistent. The searchParams property gives a live URLSearchParams view of the query.

NODE
const u = new URL("https://example.com:8443/docs/intro?lang=en#top");
console.log(u.hostname, u.port, u.pathname);

Try it

Node.js Parts of a URL

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 Changing, resolving and failing

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
new URL(input: string | { toString(): string }, base?: string | URL)
Name Description
input An absolute URL, or a relative reference when base is given.
base Absolute URL used to resolve a relative input.

Properties (all read/write except origin and searchParams): href, origin (read-only), protocol, username, password, host (hostname and port), hostname, port, pathname, search, searchParams (read-only object), hash.

Methods: toString() and toJSON() both return href. Static helpers: URL.canParse() and URL.parse(), and URL.createObjectURL() for blobs.

Errors: TypeError [ERR_INVALID_URL] when the input cannot be parsed. The error has an input property with the offending text.

Usage notes

  • Setting href replaces everything; setting other properties changes only that part and applies percent-encoding automatically.
  • port is a string, and it is the empty string when the port is the default for the scheme.
  • origin is "null" (a string) for schemes without an origin, such as file: and data:.
  • Hostnames are normalized: lowercased, and internationalized names are converted to Punycode.
  • Never concatenate user input into URLs. Build with new URL() and searchParams so special characters are encoded.
  • Use URL instead of legacy url.parse(), which has parsing differences and known security problems. See url.parse() (legacy).
  • Do not use it for file paths. Use fileURLToPath() and pathToFileURL() for conversions.
  • URLs are mutable. Copy with new URL(original) before changing one you received.