parse-url

library11.1.0jsnpmunverified

parse-url is a JavaScript/TypeScript library designed for advanced URL parsing, notably providing robust support for various Git URL formats (e.g., `git+ssh://`, `git@github.com`). It goes beyond standard URL parsing by offering detailed breakdown into components like protocols, resource, user, pathname, hash, search, and query object. The current stable version is 11.1.0, with a release cadence that includes major version updates roughly annually and more frequent minor/patch releases to address issues and update dependencies. A key differentiator is its explicit handling of Git URLs and the ability to control URL normalization via options passed to the underlying `normalize-url` library, offering more granular control than built-in or simpler parsers.

http-networking serialization

npm install parse-url

github ↗package ↗

INSTALL

IMPORT

SIG · PARSE-URL

parse-url

http-networkingjavascriptv11.1.0

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.

parseUrl

✓ import parseUrl from 'parse-url';

✗ const parseUrl = require('parse-url');

The library primarily uses ESM `import` syntax in examples. While CommonJS `require` might work in older Node.js environments, ESM is the recommended and best-supported approach, especially for type definitions.

ParseUrlResult

✓ import type { ParseUrlResult } from 'parse-url';

Import the `ParseUrlResult` type for type-checking the parsed URL object in TypeScript projects.

parseUrl (with specific path)

✓ import parseUrl from 'parse-url/dist/index.mjs';

✗ import parseUrl from 'parse-url/index.js';

For environments with strict ESM resolution or when troubleshooting, specifying the `.mjs` extension can ensure correct module loading, especially if default package exports are not configured optimally in your build system.

This quickstart demonstrates how to parse various URL formats, including standard HTTP(S) URLs with query strings and hashes, and complex Git SSH URLs, highlighting the use of the `normalize` parameter.

import parseUrl from 'parse-url'; // Example 1: Standard HTTP URL parsing console.log('HTTP URL:', parseUrl("http://ionicabizau.net/blog")); /* Output: { protocols: [ 'http' ], protocol: 'http', port: '', resource: 'ionicabizau.net', user: '', password: '', pathname: '/blog', hash: '', search: '', href: 'http://ionicabizau.net/blog', query: {} } */ // Example 2: URL with query parameters and hash console.log('\nURL with query/hash:', parseUrl("http://domain.com/path/name?foo=bar&bar=42#some-hash")); /* Output: { protocols: [ 'http' ], protocol: 'http', port: '', resource: 'domain.com', user: '', password: '', pathname: '/path/name', hash: 'some-hash', search: 'foo=bar&bar=42', href: 'http://domain.com/path/name?foo=bar&bar=42#some-hash', query: { foo: 'bar', bar: '42' } } */ // Example 3: Parsing a Git SSH URL, explicitly disabling automatic normalization console.log('\nGit SSH URL (normalized: false):', parseUrl("git+ssh://git@host.xz/path/name.git", false)); /* Output: { protocols: [ 'git', 'ssh' ], protocol: 'git', port: '', resource: 'host.xz', user: 'git', password: '', pathname: '/path/name.git', hash: '', search: '', href: 'git+ssh://git@host.xz/path/name.git', query: {} } */ // Example 4: Short-hand Git SSH URL (normalized: false) console.log('\nShort-hand Git SSH URL (normalized: false):', parseUrl("git@github.com:IonicaBizau/git-stats.git", false)); /* Output: { protocols: [ 'ssh' ], protocol: 'ssh', port: '', resource: 'github.com', user: 'git', password: '', pathname: '/IonicaBizau/git-stats.git', hash: '', search: '', href: 'git@github.com:IonicaBizau/git-stats.git', query: {} } */

Debug

Known issues

breakingVersion 11.0.0 updated the underlying `normalize-url` dependency to version 9.0.0. While `parse-url`'s API for the `normalize` parameter remains consistent, any breaking changes or behavioral shifts within `normalize-url` version 9.0.0 could indirectly affect how URLs are normalized when `parseUrl` is called with `normalize: true` or with a configuration object.

fix

Review the changelog for `normalize-url` version 9.0.0 if unexpected URL normalization behavior is observed. Test existing code paths that rely on URL normalization carefully after upgrading.

affects: >=11.0.0

breakingVersion 9.0.0 included an update to the `GIT_RE` regex to correctly parse SSH URLs containing spaces in project/repository names. This change specifically affects how certain malformed or unusual Git URLs are interpreted and might lead to different parsing results compared to earlier versions.

fix

If parsing of Git SSH URLs with spaces in paths is critical, ensure to test against version 9.0.0 or later. For older versions, manual pre-processing of such URLs might be necessary.

affects: >=9.0.0

gotchaThe `parseUrl` function throws an error if an invalid URL is provided. It does not return `null` or an object indicating failure, requiring explicit error handling.

fix

Always wrap calls to `parseUrl` in a `try...catch` block if the input URL might be malformed or invalid to prevent application crashes.

affects: >=1.0.0

gotchaThe `normalize` parameter defaults to `false`. If you expect standard URL normalization (e.g., removing redundant slashes, default ports), you must explicitly set `normalize` to `true` or pass an options object to `normalize-url`. For SSH URLs, normalization may not work as expected.

fix

Be mindful of the `normalize` parameter's default value. Pass `true` for general normalization or an object for specific `normalize-url` options. For Git URLs, it's often best to set `normalize: false` to preserve their specific structure.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: parseUrl is not a function

Attempting to `require` the module in a CommonJS environment or an incorrect default import in ESM, while the package's main export might be an ESM default export.

fix

For ESM, use `import parseUrl from 'parse-url';`. For CommonJS, ensure your `tsconfig.json` (if using TypeScript) and bundler are configured for ESM output, or try `const parseUrl = (await import('parse-url')).default;` if using dynamic import in CJS.

Error: Invalid URL

The input string provided to `parseUrl` does not conform to a recognizable URL format, causing the function to throw an error.

fix

Ensure the input URL string is well-formed. Use a `try...catch` block around `parseUrl` calls to gracefully handle and log invalid inputs, or perform basic input validation beforehand.

Property 'protocols' does not exist on type 'ParsedUrl'.

This TypeScript error indicates that the type of the `parseUrl` result is not correctly inferred or you are accessing a property that is not part of the `ParseUrlResult` type.

fix

Ensure you are using `import type { ParseUrlResult } from 'parse-url';` and explicitly typing the result, e.g., `const parsed: ParseUrlResult = parseUrl(someUrl);` to leverage the provided TypeScript definitions.

Upgrade

Version history

11.1.0latest on npm

Audit

Dependencies

normalize-urlrequiredUsed for URL normalization; its version updates can affect parse-url behavior.

Agent activity

4 hits · last 30 days

node

Resources

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

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