Comprehensive Guide to the URL Module in Node.js

The node:url module provides tools for parsing, constructing, and manipulating URLs. Node.js supports two URL APIs: WHATWG URL API — modern, browser‑compatible, standards‑based. Legacy Node.js URL API — older, Node‑specific, now discouraged. The WHATWG API is the recommended approach for all modern applications. It provides a clean, consistent interface for working with URL components, query parameters, and structured URL patterns.

WHATWG URLLegacy url.parseURLSearchParamsURLPattern

1. Introduction

The node:url module provides utilities for parsing and formatting URLs. Node.js supports both a legacy API and the modern WHATWG URL Standard used by browsers.

2. URL Strings and URL Objects

A URL string contains structured components such as protocol, hostname, port, path, query, and hash. Parsing a URL returns an object exposing these components.

3. WHATWG vs Legacy API

Node.js provides two parsing styles:

WHATWG URL → new URL() (recommended)
Legacy API → url.parse() (deprecated)

Example (WHATWG):

const myURL = new URL('https://user:[email protected]:8080/p/a/t/h?query=string#hash');

Example (Legacy):

const url = require('node:url');
const myURL = url.parse('https://user:[email protected]:8080/p/a/t/h?query=string#hash');

4. Constructing URLs

You can build URLs using setters or template literals:

const myURL = new URL('https://example.org');
myURL.pathname = '/a/b/c';
myURL.search = '?d=e';
myURL.hash = '#fgh';

5. The WHATWG URL API

The WHATWG URL class is browser‑compatible and available globally.

5.1 new URL(input, base)

Parses absolute or relative URLs. Relative URLs require a base.

5.2 Unicode & Punycode

new URL('https://測試'); // → https://xn--g6w251d/

6. URL Component Properties

6.1 url.hash

Gets/sets the fragment (#...)

6.2 url.host

Hostname + port

6.3 url.hostname

Hostname only

6.4 url.href

Full serialized URL

6.5 url.origin

Protocol + host

6.6 url.password / url.username

Authentication fields

6.7 url.pathname

Path portion

6.8 url.port

Port number (0–65535)

6.9 url.protocol

Protocol (http:, https:, ftp:, etc.)

Special Schemes

Only certain protocols are “special”: http, https, ftp, file, ws, wss.

7. url.search and url.searchParams

url.search is the raw query string. url.searchParams is a structured interface for manipulating query parameters.

Examples:

myURL.searchParams.get('abc');
myURL.searchParams.append('key', 'value');
myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');

8. URLSearchParams API

Can be used standalone or via url.searchParams.

Constructors:

Empty → new URLSearchParams()
String → new URLSearchParams('a=b&c=d')
Object → new URLSearchParams({ a: 'b' })
Iterable → new URLSearchParams([['a','b']])

Key Methods:

append(name, value)
delete(name[, value])
get(name)
getAll(name)
has(name[, value])
set(name, value)
sort()

9. Blob Object URLs

Node.js supports creating in‑memory Blob URLs:

const id = URL.createObjectURL(blob);
const restored = resolveObjectURL(id);
URL.revokeObjectURL(id);

10. URL.canParse()

Checks if a URL is valid without throwing:

URL.canParse('/foo', 'https://example.org/'); // true

11. URL.parse()

A safe parser that returns null instead of throwing.

12. URLPattern API

Experimental API for matching URLs against patterns.

Example:

const pattern = new URLPattern('https://site.com/docs/*.html');
pattern.test('https://site.com/docs/api.html'); // true

Conclusion

The node:url module provides a powerful, standards‑compliant system for parsing, constructing, and manipulating URLs. The WHATWG URL API is the modern, browser‑compatible approach and should be used for all new development. With support for URLSearchParams, Blob URLs, URLPattern, and robust parsing rules, Node.js offers a complete toolkit for working with URLs in any environment.