{"id":16274,"library":"whatwg-url","title":"WHATWG URL Standard Implementation","description":"whatwg-url provides a comprehensive and standards-compliant implementation of the WHATWG URL Standard's URL API and its underlying parsing mechanisms. It includes the `URL` and `URLSearchParams` classes, which mirror browser behavior, as well as a suite of lower-level parsing, serialization, and utility functions that are critical for projects needing fine-grained control or deep integration, such as jsdom. The current stable version is 16.0.1, with releases typically aligning with updates to the WHATWG URL specification and Node.js LTS cycles. This library differentiates itself by its strict adherence to the official specification, offering both high-level user-friendly APIs and internal algorithms for advanced use cases, ensuring consistency across different environments.","status":"active","version":"16.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/jsdom/whatwg-url","tags":["javascript"],"install":[{"cmd":"npm install whatwg-url","lang":"bash","label":"npm"},{"cmd":"yarn add whatwg-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add whatwg-url","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides international domain name (IDN) support, updated with latest Unicode versions.","package":"tr46","optional":false},{"reason":"Used for encoding support in query string parsing, specifically for `parseURL()` and `basicURLParse()`.","package":"@exodus/bytes","optional":false}],"imports":[{"note":"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`.","wrong":"const { URL } = require('whatwg-url');","symbol":"URL","correct":"import { URL } from 'whatwg-url';"},{"note":"Both `URL` and `URLSearchParams` are named exports, not default exports.","wrong":"import URLSearchParams from 'whatwg-url';","symbol":"URLSearchParams","correct":"import { URLSearchParams } from 'whatwg-url';"},{"note":"For low-level parsing functions, always use named imports. These functions operate on or return 'URL record' types, not direct `URL` instances.","wrong":"const parseURL = require('whatwg-url').parseURL;","symbol":"parseURL","correct":"import { parseURL } from 'whatwg-url';"}],"quickstart":{"code":"import { URL, URLSearchParams, parseURL, basicURLParse, serializeURL } from 'whatwg-url';\n\n// Using the high-level URL and URLSearchParams classes\nconst urlString = 'https://user:pass@example.com:8080/path/to/resource?query=value&foo=bar#fragment';\nconst myUrl = new URL(urlString);\n\nconsole.log(`Href: ${myUrl.href}`);\nconsole.log(`Origin: ${myUrl.origin}`);\nconsole.log(`Hostname: ${myUrl.hostname}`);\nconsole.log(`Pathname: ${myUrl.pathname}`);\nconsole.log(`Search: ${myUrl.search}`);\n\nconst params = myUrl.searchParams;\nconsole.log(`Query parameter 'query': ${params.get('query')}`);\nparams.append('newParam', 'newValue');\nconsole.log(`Updated search: ${myUrl.search}`);\n\n// Using low-level parsers and serializers\nconst urlRecord = parseURL('http://example.com/test?a=1', { baseURL: 'http://base.com/' });\nif (urlRecord) {\n  console.log('\\nLow-level parseURL result (scheme):', urlRecord.scheme);\n  console.log('Low-level parseURL result (host):', serializeURL(urlRecord, true));\n}\n\nconst anotherUrlRecord = basicURLParse('/path', { baseURL: 'http://foo.com/', url: null, stateOverride: 'path or authority' });\nif (anotherUrlRecord) {\n  console.log('\\nLow-level basicURLParse result:', serializeURL(anotherUrlRecord, false));\n}\n\nconst fileUrl = new URL('file:///path/to/file.txt');\nconsole.log(`\\nFile URL origin: ${fileUrl.origin}`); // Expects 'null' per WHATWG spec","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=13.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=14.1.0 <16.0.1"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"breaking","affected_versions":">=16.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ERR_REQUIRE_ESM"},{"fix":"Upgrade `whatwg-url` to version 14.1.0 or later. Alternatively, use the `new URL(input)` constructor, which is available in all versions.","cause":"`URL.parse()` was added in v14.1.0. This error indicates you are likely using an older version of `whatwg-url`.","error":"TypeError: URL.parse is not a function"},{"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.","cause":"The `URL` constructor or parsing functions expect a string as the first argument, but an object or `null`/`undefined` was provided.","error":"Error: The \"input\" argument must be of type string. Received type object"}],"ecosystem":"npm"}