url-parse

library1.5.10jsnpmunverified

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.

serialization http-networking

npm install url-parse

github ↗package ↗

INSTALL

IMPORT

SIG · URL-PARSE

url-parse

serializationjavascriptv1.5.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

URLParse (constructor/function)

✓ import URLParse from 'url-parse'; // Or for CommonJS: const URLParse = require('url-parse');

✗ import { URLParse } from 'url-parse'; const URLParse = require('url-parse').URLParse;

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.

querystringify (module)

✓ import querystringify from 'url-parse/lib/querystringify'; // Or for CommonJS: const querystringify = require('url-parse/lib/querystringify');

✗ import { querystringify } from 'url-parse';

The bundled `querystringify` module, used for parsing and stringifying query strings, is exposed via a sub-path import.

Demonstrates basic URL parsing, enabling query string parsing, resolving relative URLs with a base, and direct usage of the bundled `querystringify` module.

'use strict'; const URLParse = require('url-parse'); // Basic parsing with 'new' keyword (optional) const urlObj1 = new URLParse('https://user:pass@github.com:8080/foo/bar?baz=qux#hash'); console.log('Protocol:', urlObj1.protocol); // 'https:' console.log('Host:', urlObj1.host); // 'github.com:8080' console.log('Pathname:', urlObj1.pathname); // '/foo/bar' console.log('Query (unparsed):', urlObj1.query); // '?baz=qux' // Parsing as a function with querystring parsing enabled const urlObj2 = URLParse('http://localhost:3000/path?key=value&arr[]=1&arr[]=2', true); console.log('Protocol:', urlObj2.protocol); // 'http:' console.log('Query (parsed):', urlObj2.query); // { key: 'value', arr: [ '1', '2' ] } // Using a base URL for relative paths const baseUrl = 'http://example.com/a/b/'; const relativeUrlObj = new URLParse('../c', baseUrl); console.log('Resolved Path:', relativeUrlObj.pathname); // '/a/c' console.log('Resolved URL:', relativeUrlObj.href); // 'http://example.com/a/c' // Accessing querystringify directly const querystringify = require('url-parse/lib/querystringify'); const qString = querystringify.stringify({ name: 'Alice', age: 30 }); console.log('Stringified Query:', qString); // 'name=Alice&age=30'

Debug

Known issues

deprecatedThe 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.

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.

affects: >=1.0.0

gotchaBy 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').

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.

affects: >=0.1.0

breakingVersion 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.

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.

affects: 1.0.0

breakingVersion 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.

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.

affects: 0.1.0

Errors

Common errors & fixes

url.query remains a string, not an object

The `parser` option for query string parsing is `false` by default, meaning the query string is stored as a raw string.

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.

TypeError: URLParse is not a constructor (or 'parse is not a function')

Incorrect CommonJS or ES Module import syntax. The package primarily exports a callable constructor function as its default export.

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.

Relative URL does not resolve correctly without a base URL

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.

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/');`

Upgrade

Version history

1.5.10latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/unshiftio/url-parse ↗

packagehttps://www.npmjs.com/package/url-parse ↗