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 'iso-url';
✗ const URL = require('iso-url').URL;
While CommonJS `require` works, ESM `import` is the recommended modern approach. The default export is not `URL`.
URLSearchParams
✓ import { URLSearchParams } from 'iso-url';
✗ const URLSearchParams = require('iso-url').URLSearchParams;
Always use `URLSearchParams` for query string manipulation, as legacy `querystring` objects are not supported.
format
✓ import { format } from 'iso-url';
✗ const format = require('iso-url').format;
This utility function provides similar functionality to Node.js's `url.format`.
Demonstrates basic URL parsing, manipulation with URLSearchParams, formatting a URL object, and resolving relative URLs using `iso-url`.
import { URL, URLSearchParams, format } from 'iso-url';
// Basic URL parsing and manipulation
const urlString = 'http://localhost:3000/api/users?id=123&name=Alice';
const parsedUrl = new URL(urlString);
console.log('Hostname:', parsedUrl.hostname); // localhost
console.log('Pathname:', parsedUrl.pathname); // /api/users
console.log('Search params (raw):', parsedUrl.search); // ?id=123&name=Alice
// Using URLSearchParams to manipulate query parameters
const searchParams = new URLSearchParams(parsedUrl.search);
console.log('User ID:', searchParams.get('id')); // 123
searchParams.set('status', 'active');
parsedUrl.search = searchParams.toString();
console.log('Updated URL search:', parsedUrl.search); // ?id=123&name=Alice&status=active
// Formatting a URL object back to a string
const formattedUrl = format(parsedUrl, { auth: false, fragment: false });
console.log('Formatted URL:', formattedUrl); // http://localhost:3000/api/users?id=123&name=Alice&status=active
// Example with relative URL (requires a base)
const relativePath = '/items/new';
const baseUrl = 'http://example.com/admin/';
const resolvedUrl = new URL(relativePath, baseUrl);
console.log('Resolved relative URL:', resolvedUrl.toString()); // http://example.com/items/new
Debug
Known issues
breakingThe default behavior of the `base` parameter in the `URL` constructor changed in `v1.0.0`. It now correctly defaults to `undefined` (or derived from `location` in browsers) instead of an empty string, strictly following the WHATWG URL specification. If your application relied on the previous non-spec-compliant default for resolving relative URLs without providing a base, this change could lead to different URL outcomes or parsing errors.fixExplicitly provide a valid `base` URL as the second argument to the `URL` constructor when dealing with relative input URLs, e.g., `new URL('/path', 'https://example.com')`. affects: >=1.0.0
gotcha`iso-url` explicitly does not support Node.js's legacy `url.parse` `querystring` object properties (e.g., `url.query`). Developers migrating from older Node.js `url` module usage may expect these properties, but `iso-url` mandates the use of `URLSearchParams` for all query string manipulation, aligning with the WHATWG standard.fixAlways use the `URLSearchParams` instance available via `myUrl.searchParams` for reading, writing, and manipulating URL query parameters. For example, `myUrl.searchParams.get('param')` instead of `myUrl.query.param`. affects: >=1.0.0
gotchaThe `relative` utility function, while inspired by `dominictarr/relative-url`, does not support the specific `//:9999` syntax for protocol-relative URLs with custom ports. This could be a limitation if your application relies on this particular format for relative URL resolution.fixAvoid using the `//:port` syntax with the `relative` function. If such a format is required, pre-process the URL to a fully qualified or standard relative path before passing it to `relative`.
affects: >=1.0.0
gotchaThis package requires Node.js version `>=12`. Using it with older Node.js runtimes (e.g., Node.js 10.x or earlier) may lead to compatibility issues or runtime errors, as it relies on features introduced in later Node.js versions.fixEnsure your project's Node.js environment is updated to version 12 or newer. Update your `engines` field in `package.json` to reflect this requirement.
affects: <1.1.5 (reverted in 1.1.5, but still >=12)
Errors
Common errors & fixes
TypeError: Failed to construct 'URL': Invalid URL
The `URL` constructor was called with an invalid absolute URL string, or a relative URL string without a valid `base` argument.
fixFor absolute URLs, ensure the string is well-formed (e.g., starts with a valid protocol like `http://`). For relative URLs, always provide a valid `base` URL string or `URL` object as the second argument, e.g., `new URL('/path/to/resource', 'https://example.com/')`. TypeError: Cannot read properties of undefined (reading 'someParam') when accessing query string properties
Attempting to access a query parameter directly via a non-existent `query` or `searchObject` property on the `URL` instance, which `iso-url` does not implement to maintain WHATWG specification compliance.
fixUse the `URLSearchParams` instance available at `myUrl.searchParams` to access, modify, or iterate over query parameters. For example, use `myUrl.searchParams.get('someParam')`. Audit
Dependencies
No dependency data recorded yet.