uri-js

library4.4.1jsnpmunverified

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.

serialization http-networking

npm install uri-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · URI-JS

uri-js

serializationjavascriptv4.4.1

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.

URI

✓ import * as URI from 'uri-js';

✗ import URI from 'uri-js';

The library exports its functions as properties of a single URI object/namespace, not a default export.

parse

✓ import { parse } from 'uri-js';

✗ const { parse } = require('uri-js');

Named imports are available for individual functions, but CommonJS `require` returns the full URI object.

URI (CommonJS)

✓ const URI = require('uri-js');

For CommonJS environments, the entire API is available via `require('uri-js')` as the URI object.

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

import { parse, serialize, resolve, normalize, equal } from 'uri-js'; const exampleUri = "uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body"; const parsed = parse(exampleUri); console.log("Parsed URI:", parsed); // Expected: { scheme: 'uri', userinfo: 'user:pass', host: 'example.com', port: 123, path: '/one/two.three', query: 'q1=a1&q2=a2', fragment: 'body' } const serialized = serialize({ scheme: "http", host: "example.com", fragment: "footer" }); console.log("Serialized URI:", serialized); // Expected: http://example.com/#footer const resolved = resolve("uri://a/b/c/d?q", "../../g"); console.log("Resolved URI:", resolved); // Expected: uri://a/g const normalized = normalize("HTTP://ABC.com:80/%7Esmith/home.html"); console.log("Normalized URI:", normalized); // Expected: http://abc.com/~smith/home.html // Demonstrating IRI support const iriExample = "http://examplé.org/rosé"; const uriFromIri = serialize(parse(iriExample)); console.log("IRI to URI (punycode + escape): ", uriFromIri); // Expected: http://xn--exampl-gva.org/ros%C3%A9 const iriFromUri = serialize(parse(uriFromIri), { iri: true }); console.log("URI to IRI (unescape punycode + percent): ", iriFromUri); // Expected: http://examplé.org/rosé console.log("Equality check:", equal("example://a/b/c/%7Bfoo%7D", "eXAMPLE://a/./b/../b/%63/%7bfoo%7d")); // Expected: true

Debug

Known issues

gotchaURI.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.

fix

Pass `{ tolerant: true }` as an option to parsing functions: `URI.parse(uriString, { tolerant: true })`.

affects: >=1.0.0

gotchaHandling 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.

fix

For IRI output, use `URI.serialize(parsedObject, { iri: true })`. For parsing with unicode support, use `URI.parse(iriString, { unicodeSupport: true })`.

affects: >=1.0.0

gotchaIPv6 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.

fix

Ensure the '%' character in an IPv6 zone identifier is encoded as `%25`. For example, `//[fe80::1%25en0]` instead of `//[fe80::1%en0]`.

affects: >=1.0.0

gotchaThe 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: URI is not defined

Attempting to use `URI.parse` or other functions without correctly importing the library, often due to an incorrect ESM import for the `URI` object.

fix

Use `import * as URI from 'uri-js';` for ESM or `const URI = require('uri-js');` for CommonJS environments.

Error: URI malformed

The input string provided to a parsing function does not conform to the strict URI/IRI syntax rules defined by the RFCs.

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 })`.

Expected URI scheme, but got null/undefined

When constructing a URI object programmatically, a required component like `scheme` might be missing or invalid, leading to issues during serialization or validation.

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

Upgrade

Version history

4.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/garycourt/uri-js ↗

packagehttps://www.npmjs.com/package/uri-js ↗

homepagehttps://medialab.github.io/uri.js/ ↗