LogoENEnglish

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

~2 دقیقه مطالعه • بروزرسانی ۹ دی ۱۴۰۴

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.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article