Table of Contents

• URL
  • URL strings and URL objects
  • The WHATWG URL API
    • Class: URL
      • new URL(input[, base])
      • url.hash
      • url.host
      • url.hostname
      • url.href
      • url.origin
      • url.password
      • url.pathname
      • url.port
      • url.protocol
        • Special schemes
      • url.search
      • url.searchParams
      • url.username
      • url.toString()
      • url.toJSON()
    • Class: URLSearchParams
      • new URLSearchParams()
      • new URLSearchParams(string)
      • new URLSearchParams(obj)
      • new URLSearchParams(iterable)
      • urlSearchParams.append(name, value)
      • urlSearchParams.delete(name)
      • urlSearchParams.entries()
      • urlSearchParams.forEach(fn[, thisArg])
      • urlSearchParams.get(name)
      • urlSearchParams.getAll(name)
      • urlSearchParams.has(name)
      • urlSearchParams.keys()
      • urlSearchParams.set(name, value)
      • urlSearchParams.sort()
      • urlSearchParams.toString()
      • urlSearchParams.values()
      • urlSearchParams[Symbol.iterator]()
    • url.domainToASCII(domain)
    • url.domainToUnicode(domain)
    • url.fileURLToPath(url)
    • url.format(URL[, options])
    • url.pathToFileURL(path)
  • Legacy URL API
    • Legacy urlObject
      • urlObject.auth
      • urlObject.hash
      • urlObject.host
      • urlObject.hostname
      • urlObject.href
      • urlObject.path
      • urlObject.pathname
      • urlObject.port
      • urlObject.protocol
      • urlObject.query
      • urlObject.search
      • urlObject.slashes
    • url.format(urlObject)
    • url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
    • url.resolve(from, to)
  • Percent-encoding in URLs
    • Legacy API
    • WHATWG API

URL#

Source Code: lib/url.js

The url module provides utilities for URL resolution and parsing. It can be accessed using:

const url = require('url');

URL strings and URL objects#

A URL string is a structured string containing multiple meaningful components. When parsed, a URL object is returned containing properties for each of these components.

The url module provides two APIs for working with URLs: a legacy API that is Node.js specific, and a newer API that implements the same WHATWG URL Standard used by web browsers.

A comparison between the WHATWG and Legacy APIs is provided below. Above the URL 'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash', properties of an object returned by the legacy url.parse() are shown. Below it are properties of a WHATWG URL object.

WHATWG URL's origin property includes protocol and host, but not username or password.

┌────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                              href                                              │
├──────────┬──┬─────────────────────┬────────────────────────┬───────────────────────────┬───────┤
│ protocol │  │        auth         │          host          │           path            │ hash  │
│          │  │                     ├─────────────────┬──────┼──────────┬────────────────┤       │
│          │  │                     │    hostname     │ port │ pathname │     search     │       │
│          │  │                     │                 │      │          ├─┬──────────────┤       │
│          │  │                     │                 │      │          │ │    query     │       │
"  https:   //    user   :   pass   @ sub.example.com : 8080   /p/a/t/h  ?  query=string   #hash "
│          │  │          │          │    hostname     │ port │          │                │       │
│          │  │          │          ├─────────────────┴──────┤          │                │       │
│ protocol │  │ username │ password │          host          │          │                │       │
├──────────┴──┼──────────┴──────────┼────────────────────────┤          │                │       │
│   origin    │                     │         origin         │ pathname │     search     │ hash  │
├─────────────┴─────────────────────┴────────────────────────┴──────────┴────────────────┴───────┤
│                                              href                                              │
└────────────────────────────────────────────────────────────────────────────────────────────────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)

Parsing the URL string using the WHATWG API:

const myURL =
  new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');

Parsing the URL string using the Legacy API:

const url = require('url');
const myURL =
  url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');

The WHATWG URL API#

Class: URL#

Browser-compatible URL class, implemented by following the WHATWG URL Standard. Examples of parsed URLs may be found in the Standard itself. The URL class is also available on the global object.

In accordance with browser conventions, all properties of URL objects are implemented as getters and setters on the class prototype, rather than as data properties on the object itself. Thus, unlike legacy