{"id":13355,"library":"iso-url","title":"Isomorphic WHATWG URL API","description":"iso-url provides an isomorphic implementation of the WHATWG URL API, ensuring consistent URL parsing and manipulation across Node.js and browser environments. It wraps the native `URL` and `URLSearchParams` objects and adds some support for legacy Node.js `url.parse` properties on the `URL` instance. The package is currently at version 1.2.1 and maintains an active release cadence with regular bug fixes and dependency updates, with minor versions released every few months. A key differentiator is its unified API that bridges modern browser `window.URL` behavior with the Node.js `url` module, while also offering `format` and `relative` utilities for common URL operations. It explicitly adheres to the WHATWG specification, advocating for `URLSearchParams` and not supporting legacy `querystring` objects.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/hugomrdias/iso-url","tags":["javascript","url","node","browser","typescript"],"install":[{"cmd":"npm install iso-url","lang":"bash","label":"npm"},{"cmd":"yarn add iso-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add iso-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the recommended modern approach. The default export is not `URL`.","wrong":"const URL = require('iso-url').URL;","symbol":"URL","correct":"import { URL } from 'iso-url';"},{"note":"Always use `URLSearchParams` for query string manipulation, as legacy `querystring` objects are not supported.","wrong":"const URLSearchParams = require('iso-url').URLSearchParams;","symbol":"URLSearchParams","correct":"import { URLSearchParams } from 'iso-url';"},{"note":"This utility function provides similar functionality to Node.js's `url.format`.","wrong":"const format = require('iso-url').format;","symbol":"format","correct":"import { format } from 'iso-url';"}],"quickstart":{"code":"import { URL, URLSearchParams, format } from 'iso-url';\n\n// Basic URL parsing and manipulation\nconst urlString = 'http://localhost:3000/api/users?id=123&name=Alice';\nconst parsedUrl = new URL(urlString);\n\nconsole.log('Hostname:', parsedUrl.hostname); // localhost\nconsole.log('Pathname:', parsedUrl.pathname); // /api/users\nconsole.log('Search params (raw):', parsedUrl.search); // ?id=123&name=Alice\n\n// Using URLSearchParams to manipulate query parameters\nconst searchParams = new URLSearchParams(parsedUrl.search);\nconsole.log('User ID:', searchParams.get('id')); // 123\nsearchParams.set('status', 'active');\nparsedUrl.search = searchParams.toString();\nconsole.log('Updated URL search:', parsedUrl.search); // ?id=123&name=Alice&status=active\n\n// Formatting a URL object back to a string\nconst formattedUrl = format(parsedUrl, { auth: false, fragment: false });\nconsole.log('Formatted URL:', formattedUrl); // http://localhost:3000/api/users?id=123&name=Alice&status=active\n\n// Example with relative URL (requires a base)\nconst relativePath = '/items/new';\nconst baseUrl = 'http://example.com/admin/';\nconst resolvedUrl = new URL(relativePath, baseUrl);\nconsole.log('Resolved relative URL:', resolvedUrl.toString()); // http://example.com/items/new","lang":"typescript","description":"Demonstrates basic URL parsing, manipulation with URLSearchParams, formatting a URL object, and resolving relative URLs using `iso-url`."},"warnings":[{"fix":"Explicitly 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')`.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always 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`.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid 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`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's Node.js environment is updated to version 12 or newer. Update your `engines` field in `package.json` to reflect this requirement.","message":"This 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.","severity":"gotcha","affected_versions":"<1.1.5 (reverted in 1.1.5, but still >=12)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For 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/')`.","cause":"The `URL` constructor was called with an invalid absolute URL string, or a relative URL string without a valid `base` argument.","error":"TypeError: Failed to construct 'URL': Invalid URL"},{"fix":"Use the `URLSearchParams` instance available at `myUrl.searchParams` to access, modify, or iterate over query parameters. For example, use `myUrl.searchParams.get('someParam')`.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'someParam') when accessing query string properties"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null}