URI.js - URL Manipulation Library

Common errors

• ReferenceError: URI is not defined

  cause The URI.js library was not correctly imported or required in the current scope.
  fix For Node.js, ensure `const URI = require('urijs');` is at the top of your file. For ESM, use `import URI from 'urijs';`. In a browser, ensure the `<script src=".../URI.min.js"></script>` tag is present and loaded before your script.

• Error: Cannot find module 'uri.js' (or 'urijs/src/URITemplate')

  cause Incorrect package name used in `require()` or `import` statement, or an optional module path is wrong.
  fix Verify the package name is `urijs`. For optional modules, ensure the path is correct, e.g., `require('urijs/src/URITemplate')` or `import URITemplate from 'urijs/src/URITemplate';`.

• URL parsing yields unexpected segments (e.g., path, authority, query string appears malformed)

  cause Prior to recent security updates (v1.19.3-v1.19.11), URI.js might have parsed certain malformed URLs differently due to vulnerabilities in handling special characters or structures.
  fix Upgrade to the latest version of `urijs` (1.19.11 or newer). These versions include fixes that align parsing with modern security standards and browser behavior, which might change how previously malformed URLs are interpreted.

Warnings

• deprecated The project explicitly advises that modern browsers (and Node.js v10+) offer native `URL` and `URLSearchParams` APIs that may negate the need for URI.js. Developers should evaluate if native APIs suffice before adopting URI.js for new projects.
  Fix: For new projects or modern environments, consider using `new URL()` and `new URLSearchParams()` for URL manipulation. Example: `const url = new URL('http://example.com?a=1'); url.searchParams.set('b', '2');`
• breaking Multiple security fixes between versions 1.19.3 and 1.19.11 address vulnerabilities in `URI.parse()`, `URI.parseQuery()`, and `URI.parseAuthority()` related to handling malformed URLs. These fixes correct behavior for excessive slashes, colons, leading whitespace, CR/LF/TAB characters, scheme case-insensitivity, and backslash normalization. While enhancing security, these corrections may alter parsing results for previously 'accepted' malformed URLs, potentially breaking applications that relied on the prior, insecure parsing logic.
  Fix: Upgrade to the latest `urijs` version (1.19.11 or newer). Thoroughly test any code that parses or manipulates URLs, especially those coming from untrusted sources, to ensure the new parsing behavior aligns with expectations.
• breaking Version 1.19.7 included a security fix for `URI.parseQuery()` to prevent `__proto__` overwriting, which could lead to prototype pollution. This change might subtly affect how query parameters are parsed if they contained specific key names like `__proto__`.
  Fix: Ensure you are on version 1.19.7 or later to mitigate prototype pollution. Review any code relying on specific, unusual query parameter names that might have been affected by this fix.
• gotcha The npm package name for URI.js is `urijs` (all lowercase, no dot), not `uri.js`. Using the incorrect package name in `package.json` or `npm install` commands will result in an error or installation of a different package.
  Fix: Always use `npm install urijs` and `require('urijs')` or `import URI from 'urijs';`.

Install

• npm install urijs npm
• yarn add urijs yarn
• pnpm add urijs pnpm

Imports

• URI
  wrong:

  const URI = require('uri.js');

  correct:

  import URI from 'urijs';

  The npm package name is `urijs`, not `uri.js`. While CommonJS `require` still works, modern projects should prefer ESM `import`.
• URI

  const URI = require('urijs');

  This is the standard CommonJS import for Node.js environments.
• URITemplate
  wrong:

  import { URITemplate } from 'urijs';

  correct:

  import URITemplate from 'urijs/src/URITemplate';

  Optional modules like `URITemplate` are typically imported from their specific paths within the package, not as named exports from the root.

Quickstart

Demonstrates core URI object instantiation, fluent method chaining for URL mutation, query string normalization, and URI template expansion.

import URI from 'urijs';

const originalUrl = "http://example.org/foo.html?hello=world";

// Create a new URI object
const url = new URI(originalUrl);

// Perform a series of fluent manipulations
const modifiedUrl = url
  .username("rodneyrehm") // Add a username
  .directory("bar")     // Change directory segment
  .suffix("xml")      // Change file extension
  .query({ foo: "bar", hello: ["world", "mars"] }) // Set multiple query parameters
  .tld("com");          // Change top-level domain

console.log(`Original URL: ${originalUrl}`);
console.log(`Modified URL: ${modifiedUrl.toString()}`);

// Example of cleaning up query strings
const messyQueryUrl = URI("?&foo=bar&&foo=bar&foo=baz&").normalizeQuery();
console.log(`Cleaned Query: ${messyQueryUrl.toString()}`);

// Example of URI Templates
const expandedUri = URI.expand("/foo/{dir}/{file}", {
  dir: "bar",
  file: "world.html"
});
console.log(`Expanded URI: ${expandedUri}`);