{"id":16171,"library":"parseuri","title":"parseUri: Mighty but Tiny URI Parser","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/slevithan/parseuri","tags":["javascript","uri","url","urn"],"install":[{"cmd":"npm install parseuri","lang":"bash","label":"npm"},{"cmd":"yarn add parseuri","lang":"bash","label":"yarn"},{"cmd":"pnpm add parseuri","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v3, `parseuri` is a pure ES module and should be imported using ES module syntax. `parseUri` is the default export.","wrong":"const parseUri = require('parseuri');","symbol":"parseUri","correct":"import parseUri from 'parseuri';"},{"note":"The `setTlds` function, used for configuring top-level domains, is a named export. It was renamed from `setSld` in v3.0.0.","wrong":"import { setSld } from 'parseuri';","symbol":"setTlds","correct":"import { setTlds } from 'parseuri';"},{"note":"`parseuri` ships with JSDoc-based TypeScript definitions. `URI` is the type definition for the parsed URI object.","wrong":"import { URI } from 'parseuri';","symbol":"URI","correct":"import type { URI } from 'parseuri';"}],"quickstart":{"code":"import parseUri, { setTlds } from 'parseuri';\n\n// Configure custom TLDs, e.g., to handle 'co.uk' as a single TLD\nsetTlds({ 'co': ['uk', 'jp'], 'com': ['au'] });\n\nconst uriString = 'https://user:pass@sub1.sub2.example.co.uk:8080/p/a/t/h/a.html?q=1&param=two#hash';\nconst parsed = parseUri(uriString);\n\nconsole.log('Full URI (href):', parsed.href);\nconsole.log('Protocol:', parsed.protocol);\nconsole.log('Hostname:', parsed.hostname);\nconsole.log('Domain:', parsed.domain);\nconsole.log('TLD:', parsed.tld); // Will show 'co.uk' due to setTlds\nconsole.log('Pathname:', parsed.pathname);\nconsole.log('Query parameter \"q\":', parsed.queryParams.get('q'));\nconsole.log('All query parameters:', Object.fromEntries(parsed.queryParams.entries()));\n\n// Example of parsing a relative path (friendly mode)\nconst friendlyParsed = parseUri('example.com/file.html', true); // 'true' enables friendly mode\nconsole.log('\\nFriendly Mode Domain:', friendlyParsed.domain);\nconsole.log('Friendly Mode Filename:', friendlyParsed.filename);\n\n// Example with a non-web protocol\nconst customProtocolUri = 'git://localhost:1234/repo/project.git';\nconst customParsed = parseUri(customProtocolUri);\nconsole.log('\\nCustom Protocol:', customParsed.protocol);\nconsole.log('Custom Protocol Hostname:', customParsed.hostname);\nconsole.log('Custom Protocol Pathname:', customParsed.pathname);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace calls to `setSld` with `setTlds`. If TLD parsing is critical, you must now provide your own comprehensive TLD map to `setTlds`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate your project to use ES module `import` syntax (e.g., `import parseUri from 'parseuri';`) and ensure your environment supports ESM.","message":"Version 3.0.0 is published as a pure ES module (ESM). CommonJS `require()` syntax is no longer supported for importing `parseuri`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"If URI normalization is required, you must implement it explicitly after `parseUri` has processed the URI.","message":"`parseUri` is single-purpose and does not perform URI normalization. The native `URL` constructor, by contrast, applies certain normalization rules.","severity":"gotcha","affected_versions":"All"},{"fix":"Call `setTlds({})` if you need to disable TLD parsing or ensure no TLDs are recognized.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update your import statement to use ES module syntax: `import parseUri from 'parseuri';`. Ensure your project and environment are configured for ESM.","cause":"Attempting to use `require('parseuri')` in a CommonJS environment with `parseuri` v3.0.0 or newer, which is a pure ES module.","error":"TypeError: parseUri is not a function"},{"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.","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.","error":"ReferenceError: parseUri is not defined"},{"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`.","cause":"Accessing old URI part property names after upgrading from `parseuri` v1.x to v2.x or later.","error":"Cannot read properties of undefined (reading 'host') / Cannot read properties of undefined (reading 'source')"},{"fix":"The `setSld` function was renamed to `setTlds` in v3.0.0. Update your code to call `setTlds` instead: `import { setTlds } from 'parseuri'; setTlds(...)`.","cause":"Calling the deprecated `setSld` method after upgrading to `parseuri` v3.0.0 or newer.","error":"TypeError: parseUri(...).setSld is not a function"}],"ecosystem":"npm"}