parseuri

library3.0.2jsnpmunverified

parseUri is a highly compact and comprehensive JavaScript library for parsing URIs, URNs, and URLs into their constituent parts. The current stable version is 3.0.2, with major breaking changes introduced in v2.0.0 and v3.0.0; the latter also transitioned the package to pure ESM. Historically, releases were infrequent, but v3 indicates renewed activity. Its key differentiators include its small footprint (1KB min/gzip), zero dependencies, and robust handling of partial or invalid URIs where the built-in `URL` constructor might throw errors. It also provides a richer set of URI properties, such as `authority`, `userinfo`, `subdomain`, `domain`, `tld`, and `resource`, which are not exposed by the native `URL` object, making it suitable for complex URI analysis beyond standard web URLs. It supports a 'friendly' parsing mode and configurable multi-level TLDs.

http-networking serialization

npm install parseuri

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PARSEURI

parseuri

http-networkingjavascriptv3.0.2

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.

parseUri

✓ import parseUri from 'parseuri';

✗ const parseUri = require('parseuri');

Since v3, `parseuri` is a pure ES module and should be imported using ES module syntax. `parseUri` is the default export.

setTlds

✓ import { setTlds } from 'parseuri';

✗ import { setSld } from 'parseuri';

The `setTlds` function, used for configuring top-level domains, is a named export. It was renamed from `setSld` in v3.0.0.

URI

✓ import type { URI } from 'parseuri';

✗ import { URI } from 'parseuri';

`parseuri` ships with JSDoc-based TypeScript definitions. `URI` is the type definition for the parsed URI object.

Demonstrates importing `parseUri` and `setTlds`, parsing a complex URI, accessing various parts including query parameters, and showing usage of friendly mode and non-web protocols.

import parseUri, { setTlds } from 'parseuri'; // Configure custom TLDs, e.g., to handle 'co.uk' as a single TLD setTlds({ 'co': ['uk', 'jp'], 'com': ['au'] }); const uriString = 'https://user:pass@sub1.sub2.example.co.uk:8080/p/a/t/h/a.html?q=1&param=two#hash'; const parsed = parseUri(uriString); console.log('Full URI (href):', parsed.href); console.log('Protocol:', parsed.protocol); console.log('Hostname:', parsed.hostname); console.log('Domain:', parsed.domain); console.log('TLD:', parsed.tld); // Will show 'co.uk' due to setTlds console.log('Pathname:', parsed.pathname); console.log('Query parameter "q":', parsed.queryParams.get('q')); console.log('All query parameters:', Object.fromEntries(parsed.queryParams.entries())); // Example of parsing a relative path (friendly mode) const friendlyParsed = parseUri('example.com/file.html', true); // 'true' enables friendly mode console.log('\nFriendly Mode Domain:', friendlyParsed.domain); console.log('Friendly Mode Filename:', friendlyParsed.filename); // Example with a non-web protocol const customProtocolUri = 'git://localhost:1234/repo/project.git'; const customParsed = parseUri(customProtocolUri); console.log('\nCustom Protocol:', customParsed.protocol); console.log('Custom Protocol Hostname:', customParsed.hostname); console.log('Custom Protocol Pathname:', customParsed.pathname);

Debug

Known issues

breakingVersion 2.0.0 introduced significant breaking changes by renaming many URI part properties (e.g., `source` to `href`, `userInfo` to `userinfo`, `host` to `hostname`). Code relying on older property names will fail.

fix

Update your code to use the new URI part property names. Refer to the v2.0.0 release notes or the demo page for a comprehensive comparison.

affects: >=2.0.0

breakingVersion 3.0.0 renamed the `setSld` function to `setTlds` and removed the extremely limited, built-in list of top-level domains (TLDs). If you relied on `setSld` or the default TLD list, your domain parsing may be affected.

fix

Replace calls to `setSld` with `setTlds`. If TLD parsing is critical, you must now provide your own comprehensive TLD map to `setTlds`.

affects: >=3.0.0

breakingVersion 3.0.0 is published as a pure ES module (ESM). CommonJS `require()` syntax is no longer supported for importing `parseuri`.

fix

Migrate your project to use ES module `import` syntax (e.g., `import parseUri from 'parseuri';`) and ensure your environment supports ESM.

affects: >=3.0.0

gotchaUnlike the native `URL` constructor, `parseUri` makes a best-effort parse for invalid or non-web URIs without throwing errors. While this provides more flexibility, its interpretation of parts for non-standard protocols might differ from `URL`'s more rigid, web-centric parsing.

fix

Understand `parseUri`'s parsing logic for non-standard URIs. Use the demo page to compare results with `URL` if in doubt about specific edge cases or non-web protocols.

affects: All

gotcha`parseUri` is single-purpose and does not perform URI normalization. The native `URL` constructor, by contrast, applies certain normalization rules.

fix

If URI normalization is required, you must implement it explicitly after `parseUri` has processed the URI.

affects: All

gotchaAfter upgrading to v3.0.0, if you wish to remove TLD extensions (e.g., parsing `example.com` to have no `tld` part), you must explicitly call `setTlds({})` to clear any default or previously configured TLDs.

fix

Call `setTlds({})` if you need to disable TLD parsing or ensure no TLDs are recognized.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: parseUri is not a function

Attempting to use `require('parseuri')` in a CommonJS environment with `parseuri` v3.0.0 or newer, which is a pure ES module.

fix

Update your import statement to use ES module syntax: `import parseUri from 'parseuri';`. Ensure your project and environment are configured for ESM.

ReferenceError: parseUri is not defined

Incorrect import statement or attempting to access `parseUri` without proper module resolution, especially common when mixing CommonJS and ESM or using a bundler incorrectly.

fix

Verify that `import parseUri from 'parseuri';` is correctly placed and that your build tools (e.g., Webpack, Rollup) are configured to handle ES modules.

Cannot read properties of undefined (reading 'host') / Cannot read properties of undefined (reading 'source')

Accessing old URI part property names after upgrading from `parseuri` v1.x to v2.x or later.

fix

Refer to the v2.0.0 release notes and update property names in your code. For instance, `source` is now `href`, `host` is `hostname`, and `userInfo` is `userinfo`.

TypeError: parseUri(...).setSld is not a function

Calling the deprecated `setSld` method after upgrading to `parseuri` v3.0.0 or newer.

fix

The `setSld` function was renamed to `setTlds` in v3.0.0. Update your code to call `setTlds` instead: `import { setTlds } from 'parseuri'; setTlds(...)`.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/slevithan/parseuri ↗

packagehttps://www.npmjs.com/package/parseuri ↗

homepagehttps://slevithan.github.io/parseuri/demo/ ↗