WHATWG URL Standard Implementation

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to use `require()` to import an ESM-only package or a package that primarily targets ESM in a CommonJS context without proper configuration.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`, `.mjs` extension) and use `import { Name } from 'whatwg-url';`. If you must use CommonJS, consider using a dynamic `import()` or transpilation.

• TypeError: URL.parse is not a function

  cause `URL.parse()` was added in v14.1.0. This error indicates you are likely using an older version of `whatwg-url`.
  fix Upgrade `whatwg-url` to version 14.1.0 or later. Alternatively, use the `new URL(input)` constructor, which is available in all versions.

• Error: The "input" argument must be of type string. Received type object

  cause The `URL` constructor or parsing functions expect a string as the first argument, but an object or `null`/`undefined` was provided.
  fix Ensure the input to `new URL()` or `parseURL()` is always a valid string representation of a URL. Validate your input before passing it to the library.

Warnings

• breaking Node.js minimum version requirement has incrementally increased. Version 16.0.0 requires `^20.19.0 || ^22.12.0 || >=24.0.0`. Older versions required Node.js v20 (v15.0.0), v18 (v14.0.0), v16 (v13.0.0). Ensure your Node.js environment meets these requirements.
  Fix: Upgrade your Node.js runtime to version 20.19.0, 22.12.0, 24.0.0, or newer. Refer to the package's `engines` field for exact compatibility.
• gotcha The `URL.parse()` static method (added in v14.1.0) in versions prior to 16.0.1 returned an internal implementation object, not a proper `URL` instance. This meant `URL.parse(x) instanceof URL` would return `false`.
  Fix: Upgrade to `whatwg-url@16.0.1` or later to ensure `URL.parse()` returns a standard `URL` object. If stuck on an older version, directly use `new URL()` instead of `URL.parse()` if `instanceof URL` checks are critical.
• gotcha For `file:` URLs, `whatwg-url` strictly follows the WHATWG spec, which leaves the origin concept unspecified for `file:` URLs. As such, `myFileUrl.origin` will serialize to `"null"` (an opaque origin).
  Fix: Be aware that `file:///...` origins will be `"null"`. If you need a more specific origin for `file:` URLs in your application logic, you will need to implement custom handling outside of this library's default behavior.
• breaking The low-level parsing functions `parseURL()` and `basicURLParse()` gained an `encoding` option in v16.0.0. While this is an enhancement, it changes the signature of these functions if you were previously relying on fixed default behavior (though `URL` API always uses UTF-8).
  Fix: If using `parseURL()` or `basicURLParse()`, review your usage and explicitly set the `encoding` option if non-UTF-8 behavior is desired. The high-level `URL` constructor is not affected as it consistently uses UTF-8.

Install

• npm install whatwg-url npm
• yarn add whatwg-url yarn
• pnpm add whatwg-url pnpm

Imports

• URL
  wrong:

  const { URL } = require('whatwg-url');

  correct:

  import { URL } from 'whatwg-url';

  While CommonJS `require` might work in older Node.js versions, the package increasingly targets modern Node.js which prefers ESM imports. Use explicit named imports for `URL` and `URLSearchParams`.
• URLSearchParams
  wrong:

  import URLSearchParams from 'whatwg-url';

  correct:

  import { URLSearchParams } from 'whatwg-url';

  Both `URL` and `URLSearchParams` are named exports, not default exports.
• parseURL
  wrong:

  const parseURL = require('whatwg-url').parseURL;

  correct:

  import { parseURL } from 'whatwg-url';

  For low-level parsing functions, always use named imports. These functions operate on or return 'URL record' types, not direct `URL` instances.

Quickstart

Demonstrates the usage of `URL` and `URLSearchParams` for standard URL manipulation, and showcases the low-level `parseURL`, `basicURLParse`, and `serializeURL` functions for advanced parsing and serialization.

import { URL, URLSearchParams, parseURL, basicURLParse, serializeURL } from 'whatwg-url';

// Using the high-level URL and URLSearchParams classes
const urlString = 'https://user:pass@example.com:8080/path/to/resource?query=value&foo=bar#fragment';
const myUrl = new URL(urlString);

console.log(`Href: ${myUrl.href}`);
console.log(`Origin: ${myUrl.origin}`);
console.log(`Hostname: ${myUrl.hostname}`);
console.log(`Pathname: ${myUrl.pathname}`);
console.log(`Search: ${myUrl.search}`);

const params = myUrl.searchParams;
console.log(`Query parameter 'query': ${params.get('query')}`);
params.append('newParam', 'newValue');
console.log(`Updated search: ${myUrl.search}`);

// Using low-level parsers and serializers
const urlRecord = parseURL('http://example.com/test?a=1', { baseURL: 'http://base.com/' });
if (urlRecord) {
  console.log('\nLow-level parseURL result (scheme):', urlRecord.scheme);
  console.log('Low-level parseURL result (host):', serializeURL(urlRecord, true));
}

const anotherUrlRecord = basicURLParse('/path', { baseURL: 'http://foo.com/', url: null, stateOverride: 'path or authority' });
if (anotherUrlRecord) {
  console.log('\nLow-level basicURLParse result:', serializeURL(anotherUrlRecord, false));
}

const fileUrl = new URL('file:///path/to/file.txt');
console.log(`\nFile URL origin: ${fileUrl.origin}`); // Expects 'null' per WHATWG spec