{"id":15889,"library":"url-parse","title":"Small Footprint URL Parser","description":"url-parse is a URL parsing library designed for both Node.js and browser environments, emphasizing a small footprint. Originally created in 2014, it addressed the lack of a standardized WHATWG URL API across platforms. The package is currently at version 1.5.10 and receives infrequent updates, focusing on stability. It provides two distinct API interfaces: one that emulates the Node.js `url` module and another that behaves similarly to the modern browser `URL` interface. Its core differentiator is a pure string parsing approach, introduced in version 1.0.0, which ensures broad compatibility, particularly in environments without DOM access like Web Workers. It also bundles and exposes the `querystringify` module for robust query string handling. Critically, the project maintainers strongly recommend using the native `URL` interface for new development due to its superior security and accuracy, positioning `url-parse` primarily as a solution for legacy compatibility.","status":"maintenance","version":"1.5.10","language":"javascript","source_language":"en","source_url":"https://github.com/unshiftio/url-parse","tags":["javascript","URL","parser","uri","url","parse","query","string","querystring"],"install":[{"cmd":"npm install url-parse","lang":"bash","label":"npm"},{"cmd":"yarn add url-parse","lang":"bash","label":"yarn"},{"cmd":"pnpm add url-parse","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a constructor function (e.g., `new URLParse()`) that can also be called directly as a parsing function (e.g., `URLParse('...')`). Given its age, it is primarily a CommonJS module, and ES Module `import` typically relies on bundlers.","wrong":"import { URLParse } from 'url-parse';\nconst URLParse = require('url-parse').URLParse;","symbol":"URLParse (constructor/function)","correct":"import URLParse from 'url-parse';\n// Or for CommonJS:\nconst URLParse = require('url-parse');"},{"note":"The bundled `querystringify` module, used for parsing and stringifying query strings, is exposed via a sub-path import.","wrong":"import { querystringify } from 'url-parse';","symbol":"querystringify (module)","correct":"import querystringify from 'url-parse/lib/querystringify';\n// Or for CommonJS:\nconst querystringify = require('url-parse/lib/querystringify');"}],"quickstart":{"code":"'use strict';\n\nconst URLParse = require('url-parse');\n\n// Basic parsing with 'new' keyword (optional)\nconst urlObj1 = new URLParse('https://user:pass@github.com:8080/foo/bar?baz=qux#hash');\nconsole.log('Protocol:', urlObj1.protocol); // 'https:'\nconsole.log('Host:', urlObj1.host);     // 'github.com:8080'\nconsole.log('Pathname:', urlObj1.pathname); // '/foo/bar'\nconsole.log('Query (unparsed):', urlObj1.query); // '?baz=qux'\n\n// Parsing as a function with querystring parsing enabled\nconst urlObj2 = URLParse('http://localhost:3000/path?key=value&arr[]=1&arr[]=2', true);\nconsole.log('Protocol:', urlObj2.protocol); // 'http:'\nconsole.log('Query (parsed):', urlObj2.query); // { key: 'value', arr: [ '1', '2' ] }\n\n// Using a base URL for relative paths\nconst baseUrl = 'http://example.com/a/b/';\nconst relativeUrlObj = new URLParse('../c', baseUrl);\nconsole.log('Resolved Path:', relativeUrlObj.pathname); // '/a/c'\nconsole.log('Resolved URL:', relativeUrlObj.href); // 'http://example.com/a/c'\n\n// Accessing querystringify directly\nconst querystringify = require('url-parse/lib/querystringify');\nconst qString = querystringify.stringify({ name: 'Alice', age: 30 });\nconsole.log('Stringified Query:', qString); // 'name=Alice&age=30'\n","lang":"javascript","description":"Demonstrates basic URL parsing, enabling query string parsing, resolving relative URLs with a base, and direct usage of the bundled `querystringify` module."},"warnings":[{"fix":"For new projects, use `new URL()` or `URL.parse()` (if available) and `URLSearchParams` for query string manipulation. Review existing code for potential security implications if `url-parse` handles untrusted input.","message":"The maintainers strongly recommend using the native WHATWG `URL` API (available in Node.js and modern browsers) for new development. They cite better security and accuracy, positioning `url-parse` primarily for legacy compatibility due to inconsistencies that can be weaponized in security attacks.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"When creating a `URLParse` instance, pass `true` as the second argument: `new URLParse('your-url', true)` to enable default query string parsing. Alternatively, use `urlParseInstance.set('query', { /* new object */ }, true);` to trigger re-parsing.","message":"By default, the `parser` option for querystring parsing is `false`. To parse the query string into an object, you must explicitly pass `true` as the second argument to the `URLParse` constructor/function, or a custom parsing function. Otherwise, the `query` property will remain an unparsed string (e.g., '?key=value').","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly test parsing behavior for critical URL patterns when migrating to or from version 1.0.0, especially if relying on specific outcomes for unusual or malformed URLs.","message":"Version 1.0.0 fundamentally changed the parsing strategy from a RegExp-based solution to a pure string parsing approach. While intended to improve cross-environment compatibility and reduce Firefox-specific issues, this was a significant internal rewrite that could introduce subtle differences in how certain malformed or edge-case URLs are parsed compared to prior versions.","severity":"breaking","affected_versions":"1.0.0"},{"fix":"If migrating from pre-0.1 versions, ensure your environment supports the new parsing mechanism. For Web Worker compatibility, version 0.1 was an improvement, but later versions refined parsing further.","message":"Version 0.1 moved from a DOM-based parsing solution (leveraging `<a>` elements) to a Regular Expression solution. This change specifically impacted environments without DOM access, such as Web Workers. While later superseded, it represents a significant shift in compatibility and parsing technique for that version.","severity":"breaking","affected_versions":"0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Pass `true` as the second argument to the `URLParse` constructor/function: `const url = new URLParse('http://example.com?a=1', true);` to enable default querystring parsing.","cause":"The `parser` option for query string parsing is `false` by default, meaning the query string is stored as a raw string.","error":"url.query remains a string, not an object"},{"fix":"For CommonJS: `const URLParse = require('url-parse');`. For ES Modules, which might require bundler support for this CJS-first package: `import URLParse from 'url-parse';`. Avoid named imports like `import { URLParse } from 'url-parse';` for the main export.","cause":"Incorrect CommonJS or ES Module import syntax. The package primarily exports a callable constructor function as its default export.","error":"TypeError: URLParse is not a constructor (or 'parse is not a function')"},{"fix":"Provide a base URL string or `URLParse` object as the second argument when parsing relative URLs: `const resolvedUrl = new URLParse('/images/logo.png', 'http://example.com/');`","cause":"When parsing a relative URL string (e.g., '/path' or '../file.html'), `url-parse` requires a `baseURL` argument to resolve it into an absolute URL. Without it, the result might be unexpected or incomplete.","error":"Relative URL does not resolve correctly without a base URL"}],"ecosystem":"npm"}