parseUri: Mighty but Tiny URI Parser

Common errors

• TypeError: parseUri is not a function

  cause 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

  cause 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')

  cause 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

  cause 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(...)`.

Warnings

• breaking Version 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.
• breaking Version 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`.
• breaking Version 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.
• gotcha Unlike 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.
• 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.
• gotcha After 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.

Install

• npm install parseuri npm
• yarn add parseuri yarn
• pnpm add parseuri pnpm

Imports

• parseUri
  wrong:

  const parseUri = require('parseuri');

  correct:

  import parseUri from 'parseuri';

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

  import { setSld } from 'parseuri';

  correct:

  import { setTlds } 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
  wrong:

  import { URI } from 'parseuri';

  correct:

  import type { URI } from 'parseuri';

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

Quickstart

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);