Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
URL
✓ import { URL } from 'whatwg-url';
✗ const { URL } = require('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
✓ import { URLSearchParams } from 'whatwg-url';
✗ import URLSearchParams from 'whatwg-url';
Both `URL` and `URLSearchParams` are named exports, not default exports.
parseURL
✓ import { parseURL } from 'whatwg-url';
✗ const parseURL = require('whatwg-url').parseURL;
For low-level parsing functions, always use named imports. These functions operate on or return 'URL record' types, not direct `URL` instances.
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
Debug
Known issues
breakingNode.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.fixUpgrade 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.
affects: >=13.0.0
gotchaThe `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`.fixUpgrade 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.
affects: >=14.1.0 <16.0.1
gotchaFor `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).fixBe 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.
affects: >=1.0.0
breakingThe 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).fixIf 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.
affects: >=16.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to use `require()` to import an ESM-only package or a package that primarily targets ESM in a CommonJS context without proper configuration.
fixEnsure 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
`URL.parse()` was added in v14.1.0. This error indicates you are likely using an older version of `whatwg-url`.
fixUpgrade `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
The `URL` constructor or parsing functions expect a string as the first argument, but an object or `null`/`undefined` was provided.
fixEnsure 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.
Audit
Dependencies
tr46requiredProvides international domain name (IDN) support, updated with latest Unicode versions.
@exodus/bytesrequiredUsed for encoding support in query string parsing, specifically for `parseURL()` and `basicURLParse()`.