{"id":12761,"library":"uri-js","title":"URI.js URI/IRI Parser","description":"uri-js is a comprehensive JavaScript library designed for parsing, validating, resolving, normalizing, and comparing URIs and IRIs, strictly adhering to RFC 3986 (URI) and RFC 3987 (IRI) specifications. It also incorporates support for IDNA (RFC 5890), IPv6 Address (RFC 5952), and IPv6 Zone Identifier (RFC 6874). The current stable version is 4.4.1. The library is actively maintained, with a focus on robust RFC compliance and broad environment compatibility (browsers, Node.js). Key differentiators include its scheme-extendable architecture, extensive test suite, and compact size (6.4kb gzipped, 17kb deflated), making it a reliable choice for applications requiring precise URI manipulation without significant overhead. It offers granular control over parsing and serialization through an extensive options object.","status":"active","version":"4.4.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/garycourt/uri-js","tags":["javascript","URI","IRI","IDN","URN","UUID","HTTP","HTTPS","WS","typescript"],"install":[{"cmd":"npm install uri-js","lang":"bash","label":"npm"},{"cmd":"yarn add uri-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add uri-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports its functions as properties of a single URI object/namespace, not a default export.","wrong":"import URI from 'uri-js';","symbol":"URI","correct":"import * as URI from 'uri-js';"},{"note":"Named imports are available for individual functions, but CommonJS `require` returns the full URI object.","wrong":"const { parse } = require('uri-js');","symbol":"parse","correct":"import { parse } from 'uri-js';"},{"note":"For CommonJS environments, the entire API is available via `require('uri-js')` as the URI object.","symbol":"URI (CommonJS)","correct":"const URI = require('uri-js');"}],"quickstart":{"code":"import { parse, serialize, resolve, normalize, equal } from 'uri-js';\n\nconst exampleUri = \"uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body\";\nconst parsed = parse(exampleUri);\n\nconsole.log(\"Parsed URI:\", parsed);\n// Expected: { scheme: 'uri', userinfo: 'user:pass', host: 'example.com', port: 123, path: '/one/two.three', query: 'q1=a1&q2=a2', fragment: 'body' }\n\nconst serialized = serialize({ scheme: \"http\", host: \"example.com\", fragment: \"footer\" });\nconsole.log(\"Serialized URI:\", serialized);\n// Expected: http://example.com/#footer\n\nconst resolved = resolve(\"uri://a/b/c/d?q\", \"../../g\");\nconsole.log(\"Resolved URI:\", resolved);\n// Expected: uri://a/g\n\nconst normalized = normalize(\"HTTP://ABC.com:80/%7Esmith/home.html\");\nconsole.log(\"Normalized URI:\", normalized);\n// Expected: http://abc.com/~smith/home.html\n\n// Demonstrating IRI support\nconst iriExample = \"http://examplé.org/rosé\";\nconst uriFromIri = serialize(parse(iriExample));\nconsole.log(\"IRI to URI (punycode + escape):\n\", uriFromIri);\n// Expected: http://xn--exampl-gva.org/ros%C3%A9\n\nconst iriFromUri = serialize(parse(uriFromIri), { iri: true });\nconsole.log(\"URI to IRI (unescape punycode + percent):\n\", iriFromUri);\n// Expected: http://examplé.org/rosé\n\nconsole.log(\"Equality check:\", equal(\"example://a/b/c/%7Bfoo%7D\", \"eXAMPLE://a/./b/../b/%63/%7bfoo%7d\"));\n// Expected: true\n","lang":"typescript","description":"This quickstart demonstrates the core functionalities of URI.js including parsing, serializing, resolving, normalizing, and comparing URIs, alongside its specific support for Internationalized Resource Identifiers (IRIs)."},"warnings":[{"fix":"Pass `{ tolerant: true }` as an option to parsing functions: `URI.parse(uriString, { tolerant: true })`.","message":"URI.js strictly adheres to RFC standards. If you are dealing with malformed or non-compliant URIs that need to be parsed, you might need to enable the `tolerant` option during parsing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For IRI output, use `URI.serialize(parsedObject, { iri: true })`. For parsing with unicode support, use `URI.parse(iriString, { unicodeSupport: true })`.","message":"Handling Internationalized Resource Identifiers (IRIs) requires specific options. By default, IRIs are converted to their URI-compatible (Punycode and percent-encoded) forms. To work with unescaped non-ASCII characters, `iri: true` for serialization and `unicodeSupport: true` for parsing are necessary.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the '%' character in an IPv6 zone identifier is encoded as `%25`. For example, `//[fe80::1%25en0]` instead of `//[fe80::1%en0]`.","message":"IPv6 Zone Identifiers require specific percent-encoding for the '%' character itself (e.g., `%25`) within the host component as per RFC 6874. Failure to correctly encode the zone identifier will result in incorrect parsing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `URI.equal()` for comparison where possible, as it accounts for these normalizations. If manually comparing, apply normalization first or be aware of standard port elision and case insensitivity for certain URI components.","message":"The library automatically normalizes common URI schemes (HTTP, HTTPS, WS, WSS) according to their respective RFCs, which might alter host casing or port numbers (e.g., port 80 for HTTP). Be aware of these automatic normalizations when comparing URIs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import * as URI from 'uri-js';` for ESM or `const URI = require('uri-js');` for CommonJS environments.","cause":"Attempting to use `URI.parse` or other functions without correctly importing the library, often due to an incorrect ESM import for the `URI` object.","error":"ReferenceError: URI is not defined"},{"fix":"Review the URI string for syntax errors. If parsing non-standard or 'dirty' URIs, consider using the `{ tolerant: true }` option: `URI.parse(uriString, { tolerant: true })`.","cause":"The input string provided to a parsing function does not conform to the strict URI/IRI syntax rules defined by the RFCs.","error":"Error: URI malformed"},{"fix":"Ensure all necessary URI components (e.g., `scheme`, `host` for absolute URIs) are provided and correctly formatted in the object passed to `URI.serialize` or `URI.build` (if using an extended API).","cause":"When constructing a URI object programmatically, a required component like `scheme` might be missing or invalid, leading to issues during serialization or validation.","error":"Expected URI scheme, but got null/undefined"}],"ecosystem":"npm"}