Lines Matching full:url
1 # URL chapter
7 <!-- source_link=lib/url.js -->
9 The `node:url` module provides utilities for URL resolution and parsing. It can
13 import url from 'node:url';
17 const url = require('node:url');
20 ## URL strings and URL objects
22 A URL string is a structured string containing multiple meaningful components.
23 When parsed, a URL object is returned containing properties for each of these
26 The `node:url` module provides two APIs for working with URLs: a legacy API that
28 [WHATWG URL Standard][] used by web browsers.
30 A comparison between the WHATWG and legacy APIs is provided below. Above the URL
32 of an object returned by the legacy `url.parse()` are shown. Below it are
33 properties of a WHATWG `URL` object.
35 WHATWG URL's `origin` property includes `protocol` and `host`, but not
59 Parsing the URL string using the WHATWG API:
63 new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
66 Parsing the URL string using the legacy API:
69 import url from 'node:url';
71 url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
75 const url = require('node:url');
77 url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
80 ### Constructing a URL from component parts and getting the constructed string
82 It is possible to construct a WHATWG URL from component parts using either the
86 const myURL = new URL('https://example.org');
96 const myURL = new URL(`https://example.org${pathname}${search}${hash}`);
99 To get the constructed URL string, use the `href` property accessor:
105 ## The WHATWG URL API
107 ### Class: `URL`
115 pr-url: https://github.com/nodejs/node/pull/18281
119 Browser-compatible `URL` class, implemented by following the WHATWG URL
121 The `URL` class is also available on the global object.
123 In accordance with browser conventions, all properties of `URL` objects
126 using the `delete` keyword on any properties of `URL` objects (e.g. `delete
130 #### `new URL(input[, base])` argument
135 pr-url: https://github.com/nodejs/node/pull/47339
139 * `input` {string} The absolute or relative input URL to parse. If `input`
142 * `base` {string} The base URL to resolve against if the `input` is not
145 Creates a new `URL` object by parsing the `input` relative to the `base`. If
146 `base` is passed as a string, it will be parsed equivalent to `new URL(base)`.
149 const myURL = new URL('/foo', 'https://example.org/');
153 The URL constructor is accessible as a property on the global object.
154 It can also be imported from the built-in url module:
157 import { URL } from 'node:url';
158 console.log(URL === globalThis.URL); // Prints 'true'.
162 console.log(URL === require('node:url').URL); // Prints 'true'.
170 const myURL = new URL({ toString: () => 'https://example.org/' });
178 const myURL = new URL('https://測試');
182 In cases where it is not known in advance if `input` is an absolute URL
184 the `URL` object is what is expected.
187 let myURL = new URL('http://Example.com/', 'https://example.org/');
190 myURL = new URL('https://Example.com/', 'https://example.org/');
193 myURL = new URL('foo://Example.com/', 'https://example.org/');
196 myURL = new URL('http:Example.com/', 'https://example.org/');
199 myURL = new URL('https:Example.com/', 'https://example.org/');
202 myURL = new URL('foo:Example.com/', 'https://example.org/');
206 #### `url.hash`
210 Gets and sets the fragment portion of the URL.
213 const myURL = new URL('https://example.org/foo#bar');
222 Invalid URL characters included in the value assigned to the `hash` property
224 percent-encode may vary somewhat from what the [`url.parse()`][] and
225 [`url.format()`][] methods would produce.
227 #### `url.host`
231 Gets and sets the host portion of the URL.
234 const myURL = new URL('https://example.org:81/foo');
245 #### `url.hostname`
249 Gets and sets the host name portion of the URL. The key difference between
250 `url.host` and `url.hostname` is that `url.hostname` does _not_ include the
254 const myURL = new URL('https://example.org:81/foo');
271 #### `url.href`
275 Gets and sets the serialized URL.
278 const myURL = new URL('https://example.org/foo');
288 [`url.toString()`][].
291 new `URL` object using [`new URL(value)`][`new URL()`]. Each of the `URL`
294 If the value assigned to the `href` property is not a valid URL, a `TypeError`
297 #### `url.origin`
302 pr-url: https://github.com/nodejs/node/pull/33325
303 description: The scheme "gopher" is no longer special and `url.origin` now
309 Gets the read-only serialization of the URL's origin.
312 const myURL = new URL('https://example.org/foo/bar?baz');
318 const idnURL = new URL('https://測試');
326 #### `url.password`
330 Gets and sets the password portion of the URL.
333 const myURL = new URL('https://abc:xyz@example.com');
342 Invalid URL characters included in the value assigned to the `password` property
344 percent-encode may vary somewhat from what the [`url.parse()`][] and
345 [`url.format()`][] methods would produce.
347 #### `url.pathname`
351 Gets and sets the path portion of the URL.
354 const myURL = new URL('https://example.org/abc/xyz?123');
363 Invalid URL characters included in the value assigned to the `pathname`
365 to percent-encode may vary somewhat from what the [`url.parse()`][] and
366 [`url.format()`][] methods would produce.
368 #### `url.port`
373 pr-url: https://github.com/nodejs/node/pull/33325
379 Gets and sets the port portion of the URL.
383 `URL` objects given `protocol` will result in the `port` value becoming
406 const myURL = new URL('https://example.org:8888');
449 Leading numbers up to the decimal point will be set as the URL's port,
458 #### `url.protocol`
462 Gets and sets the protocol portion of the URL.
465 const myURL = new URL('https://example.org');
474 Invalid URL protocol values assigned to the `protocol` property are ignored.
481 pr-url: https://github.com/nodejs/node/pull/33325
485 The [WHATWG URL Standard][] considers a handful of URL protocol schemes to be
486 _special_ in terms of how they are parsed and serialized. When a URL is
487 parsed using one of these special protocols, the `url.protocol` property
494 const u = new URL('http://example.org');
504 const u = new URL('http://example.org');
514 const u = new URL('fish://example.org');
520 According to the WHATWG URL Standard, special protocol schemes are `ftp`,
523 #### `url.search`
527 Gets and sets the serialized query portion of the URL.
530 const myURL = new URL('https://example.org/abc?123');
539 Any invalid URL characters appearing in the value assigned the `search`
541 characters to percent-encode may vary somewhat from what the [`url.parse()`][]
542 and [`url.format()`][] methods would produce.
544 #### `url.searchParams`
549 URL. This property is read-only but the `URLSearchParams` object it provides
550 can be used to mutate the URL instance; to replace the entirety of query
551 parameters of the URL, use the [`url.search`][] setter. See
554 Use care when using `.searchParams` to modify the `URL` because,
557 instance, the `URL` object will not percent encode the ASCII tilde (`~`)
561 const myURL = new URL('https://example.org/abc?foo=~bar');
565 // Modify the URL via searchParams...
571 #### `url.username`
575 Gets and sets the username portion of the URL.
578 const myURL = new URL('https://abc:xyz@example.com');
587 Any invalid URL characters appearing in the value assigned the `username`
589 characters to percent-encode may vary somewhat from what the [`url.parse()`][]
590 and [`url.format()`][] methods would produce.
592 #### `url.toString()`
596 The `toString()` method on the `URL` object returns the serialized URL. The
597 value returned is equivalent to that of [`url.href`][] and [`url.toJSON()`][].
599 #### `url.toJSON()`
603 The `toJSON()` method on the `URL` object returns the serialized URL. The
604 value returned is equivalent to that of [`url.href`][] and
605 [`url.toString()`][].
607 This method is automatically called when an `URL` object is serialized
612 new URL('https://www.example.com'),
613 new URL('https://test.example.org'),
619 #### `URL.createObjectURL(blob)` argument
630 Creates a `'blob:nodedata:...'` URL string that represents the given {Blob}
640 const id = URL.createObjectURL(blob);
649 `URL.revokeObjectURL()` is called to remove it.
655 #### `URL.revokeObjectURL(id)` argument
663 * `id` {string} A `'blob:nodedata:...` URL string returned by a prior call to
664 `URL.createObjectURL()`.
669 #### `URL.canParse(input[, base])` argument
675 * `input` {string} The absolute or relative input URL to parse. If `input`
678 * `base` {string} The base URL to resolve against if the `input` is not
682 Checks if an `input` relative to the `base` can be parsed to a `URL`.
685 const isValid = URL.canParse('/foo', 'https://example.org/'); // true
687 const isNotValid = URL.canParse('/foo'); // false
698 pr-url: https://github.com/nodejs/node/pull/18281
703 `URL`. The `URLSearchParams` class can also be used standalone with one of the
710 On the other hand, this API is designed purely for URL query strings.
713 const myURL = new URL('https://example.org/?abc=123');
867 pr-url: https://github.com/nodejs/node/pull/47885
894 pr-url: https://github.com/nodejs/node/pull/41678
906 const myURL = new URL('https://example.org/?a=b&c=d');
937 pr-url: https://github.com/nodejs/node/pull/47885
1056 ### `url.domainToASCII(domain)`
1064 pr-url: https://github.com/nodejs/node/pull/47339
1074 It performs the inverse operation to [`url.domainToUnicode()`][].
1077 import url from 'node:url';
1079 console.log(url.domainToASCII('español.com'));
1081 console.log(url.domainToASCII('中文.com'));
1083 console.log(url.domainToASCII('xn--iñvalid.com'));
1088 const url = require('node:url');
1090 console.log(url.domainToASCII('español.com'));
1092 console.log(url.domainToASCII('中文.com'));
1094 console.log(url.domainToASCII('xn--iñvalid.com'));
1098 ### `url.domainToUnicode(domain)`
1106 pr-url: https://github.com/nodejs/node/pull/47339
1116 It performs the inverse operation to [`url.domainToASCII()`][].
1119 import url from 'node:url';
1121 console.log(url.domainToUnicode('xn--espaol-zwa.com'));
1123 console.log(url.domainToUnicode('xn--fiq228c.com'));
1125 console.log(url.domainToUnicode('xn--iñvalid.com'));
1130 const url = require('node:url');
1132 console.log(url.domainToUnicode('xn--espaol-zwa.com'));
1134 console.log(url.domainToUnicode('xn--fiq228c.com'));
1136 console.log(url.domainToUnicode('xn--iñvalid.com'));
1140 ### `url.fileURLToPath(url)`
1146 * `url` {URL | string} The file URL string or URL object to convert to a path.
1153 import { fileURLToPath } from 'node:url';
1155 const __filename = fileURLToPath(import.meta.url);
1157 new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
1160 new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
1163 new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
1166 new URL('file:///hello world').pathname; // Incorrect: /hello%20world
1171 const { fileURLToPath } = require('node:url');
1172 new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
1175 new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
1178 new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
1181 new URL('file:///hello world').pathname; // Incorrect: /hello%20world
1185 ### `url.format(URL[, options])`
1191 * `URL` {URL} A [WHATWG URL][] object
1193 * `auth` {boolean} `true` if the serialized URL string should include the
1195 * `fragment` {boolean} `true` if the serialized URL string should include the
1197 * `search` {boolean} `true` if the serialized URL string should include the
1200 component of the URL string should be encoded directly as opposed to being
1204 Returns a customizable serialization of a URL `String` representation of a
1205 [WHATWG URL][] object.
1207 The URL object has both a `toString()` method and `href` property that return
1208 string serializations of the URL. These are not, however, customizable in
1209 any way. The `url.format(URL[, options])` method allows for basic customization
1213 import url from 'node:url';
1214 const myURL = new URL('https://a:b@測試?abc#foo');
1222 console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
1227 const url = require('node:url');
1228 const myURL = new URL('https://a:b@測試?abc#foo');
1236 console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
1240 ### `url.pathToFileURL(path)`
1246 * `path` {string} The path to convert to a File URL.
1247 * Returns: {URL} The file URL object.
1249 This function ensures that `path` is resolved absolutely, and that the URL
1250 control characters are correctly encoded when converting into a File URL.
1253 import { pathToFileURL } from 'node:url';
1255 new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
1258 new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
1263 const { pathToFileURL } = require('node:url');
1264 new URL(__filename); // Incorrect: throws (POSIX)
1265 new URL(__filename); // Incorrect: C:\... (Windows)
1269 new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
1272 new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
1276 ### `url.urlToHttpOptions(url)`
1284 pr-url: https://github.com/nodejs/node/pull/46989
1286 properties of the `url` argument.
1289 * `url` {URL} The [WHATWG URL][] object to convert to an options object.
1294 * `hash` {string} The fragment portion of the URL.
1295 * `search` {string} The serialized query portion of the URL.
1296 * `pathname` {string} The path portion of the URL.
1301 * `href` {string} The serialized URL.
1306 This utility function converts a URL object into an ordinary options object as
1310 import { urlToHttpOptions } from 'node:url';
1311 const myURL = new URL('https://a:b@測試?abc#foo');
1329 const { urlToHttpOptions } = require('node:url');
1330 const myURL = new URL('https://a:b@測試?abc#foo');
1347 ## Legacy URL API
1354 pr-url: https://github.com/nodejs/node/pull/37784
1357 pr-url: https://github.com/nodejs/node/pull/22715
1361 > Stability: 3 - Legacy: Use the WHATWG URL API instead.
1370 pr-url: https://github.com/nodejs/node/pull/37784
1373 pr-url: https://github.com/nodejs/node/pull/22715
1374 description: The Legacy URL API is deprecated. Use the WHATWG URL API.
1377 > Stability: 3 - Legacy: Use the WHATWG URL API instead.
1379 The legacy `urlObject` (`require('node:url').Url` or
1380 `import { Url } from 'node:url'`) is
1381 created and returned by the `url.parse()` function.
1385 The `auth` property is the username and password portion of the URL, also
1395 The `hash` property is the fragment identifier portion of the URL including the
1402 The `host` property is the full lower-cased host portion of the URL, including
1416 The `href` property is the full URL string that was parsed with both the
1432 The `pathname` property consists of the entire path section of the URL. This
1449 The `protocol` property identifies the URL's lower-cased protocol scheme.
1458 determined by the `parseQueryString` argument passed to `url.parse()`.
1468 URL, including the leading ASCII question mark (`?`) character.
1480 ### `url.format(urlObject)`
1486 pr-url: https://github.com/nodejs/node/pull/38631
1489 the URL to be re-parsed differently.
1493 pr-url: https://github.com/nodejs/node/pull/37784
1496 pr-url: https://github.com/nodejs/node/pull/22715
1497 description: The Legacy URL API is deprecated. Use the WHATWG URL API.
1499 pr-url: https://github.com/nodejs/node/pull/7234
1506 > Stability: 3 - Legacy: Use the WHATWG URL API instead.
1508 * `urlObject` {Object|string} A URL object (as returned by `url.parse()` or
1510 it to `url.parse()`.
1512 The `url.format()` method returns a formatted URL string derived from
1516 const url = require('node:url');
1517 url.format({
1530 If `urlObject` is not an object or a string, `url.format()` will throw a
1585 ### `url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`
1591 pr-url: https://github.com/nodejs/node/pull/44919
1596 pr-url: https://github.com/nodejs/node/pull/37784
1599 pr-url: https://github.com/nodejs/node/pull/26941
1600 description: The `pathname` property on the returned URL object is now `/`
1604 pr-url: https://github.com/nodejs/node/pull/22715
1605 description: The Legacy URL API is deprecated. Use the WHATWG URL API.
1607 pr-url: https://github.com/nodejs/node/pull/13606
1608 description: The `search` property on the returned URL object is now `null`
1612 > Stability: 0 - Deprecated: Use the WHATWG URL API instead.
1614 * `urlString` {string} The URL string to parse.
1617 method. If `false`, the `query` property on the returned URL object will be an
1625 The `url.parse()` method takes a URL string, parses it, and returns a URL
1632 `url.parse()` uses a lenient, non-standard algorithm for parsing URL
1635 input. CVEs are not issued for `url.parse()` vulnerabilities. Use the
1636 [WHATWG URL][] API instead.
1638 ### `url.resolve(from, to)`
1646 pr-url: https://github.com/nodejs/node/pull/37784
1649 pr-url: https://github.com/nodejs/node/pull/22715
1650 description: The Legacy URL API is deprecated. Use the WHATWG URL API.
1652 pr-url: https://github.com/nodejs/node/pull/8215
1658 pr-url: https://github.com/nodejs/node/pull/8214
1661 pr-url: https://github.com/nodejs/node/pull/1480
1666 > Stability: 3 - Legacy: Use the WHATWG URL API instead.
1668 * `from` {string} The base URL to use if `to` is a relative URL.
1669 * `to` {string} The target URL to resolve.
1671 The `url.resolve()` method resolves a target URL relative to a base URL in a
1675 const url = require('node:url');
1676 url.resolve('/one/two/three', 'four'); // '/one/two/four'
1677 url.resolve('http://example.com/', '/one'); // 'http://example.com/one'
1678 url.resolve('http://example.com/one', '/two'); // 'http://example.com/two'
1681 To achieve the same result using the WHATWG URL API:
1685 const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
1687 // `from` is a relative URL.
1706 located within the structure of the URL.
1711 automatically escaped in the properties of URL objects:
1722 The [WHATWG URL Standard][] uses a more selective and fine grained approach to
1744 passwords encoded within the URL. The _path percent-encode set_ is used for the
1745 path of most URLs. The _fragment percent-encode set_ is used for URL fragments.
1754 const myURL = new URL('https://%CF%80.example.com/foo');
1762 [WHATWG URL]: #the-whatwg-url-api
1763 [WHATWG URL Standard]: https://url.spec.whatwg.org/
1772 [`new URL()`]: #new-urlinput-base
1774 [`url.domainToASCII()`]: #urldomaintoasciidomain
1775 [`url.domainToUnicode()`]: #urldomaintounicodedomain
1776 [`url.format()`]: #urlformaturlobject
1777 [`url.href`]: #urlhref
1778 [`url.parse()`]: #urlparseurlstring-parsequerystring-slashesdenotehost
1779 [`url.search`]: #urlsearch
1780 [`url.toJSON()`]: #urltojson
1781 [`url.toString()`]: #urltostring
1785 [examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing