Table of Contents

• URL

  • URL Strings and URL Objects

  • The WHATWG URL API

    • Class: URL

      • Constructor: 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

      • Constructor: new URLSearchParams()
      • Constructor: new URLSearchParams(string)
      • Constructor: new URLSearchParams(obj)
      • Constructor: 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#

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.

While the Legacy API has not been deprecated, it is maintained solely for backwards compatibility with existing applications. New application code should use the WHATWG API.

A comparison between the WHATWG and Legacy APIs is provided below. Above the URL 'http://user:pass@sub.host.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.host.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.host.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.host.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 urlObjects, using the delete keyword on any properties of URL objects (e.g. delete myURL.protocol, delete myURL.pathname, etc) has no effect but will still return true.

Constructor: new URL(input[, base])#

• input <string> The absolute or relative input URL to parse. If input is relative, then base is required. If input is absolute, the base is ignored.
• base <string> | <URL> The base URL to resolve against if the input is not absolute.

Creates a new URL object by parsing the input relative to the base. If base is passed as a string, it will be parsed equivalent to new URL(base).

const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo

A TypeError will be thrown if the input or base are not valid URLs. Note that an effort will be made to coerce the given values into strings. For instance:

const myURL = new URL({ toString: () => 'https://example.org/' });
// https://example.org/

Unicode characters appearing within the hostname of input will be automatically converted to ASCII using the Punycode algorithm.

const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba/

This feature is only available if the node executable was compiled with ICU enabled. If not, the domain names are passed through unchanged.

In cases where it is not known in advance if input is an absolute URL and a base is provided, it is advised to validate that the origin of the URL object is what is expected.

let myURL = new URL('http://anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/

myURL = new URL('https://anotherExample.org/', 'https://example.org/');
// https://anotherexample.org/

myURL = new URL('foo://anotherExample.org/', 'https://example.org/');
// foo://anotherExample.org/

myURL = new URL('http:anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/

myURL = new URL('https:anotherExample.org/', 'https://example.org/');
// https://example.org/anotherExample.org/

myURL = new URL('foo:anotherExample.org/', 'https://example.org/');
// foo:anotherExample.org/

url.hash#

• <string>

Gets and sets the fragment portion of the URL.

const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz

Invalid URL characters included in the value assigned to the hash property are percent-encoded. Note that the selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.host