{"id":12324,"library":"urijs","title":"URI.js - URL Manipulation Library","description":"URI.js is a robust JavaScript library designed for parsing, manipulating, and constructing URLs (Uniform Resource Locators) and URIs (Uniform Resource Identifiers). Its current stable version is 1.19.11, with development focused on security patching and maintenance rather than new feature additions. The library has historically seen frequent updates to address various parsing vulnerabilities, particularly concerning malformed URLs, which highlights its commitment to secure URI handling. While it provides a comprehensive and fluent API for complex URL transformations, the project explicitly recommends developers leverage native browser APIs like `URL` and `URLSearchParams` for modern web environments, suggesting URI.js is most suitable for legacy projects, environments lacking native URL APIs, or for advanced scenarios such as URI template expansion. It differentiates itself by offering a mutable, chaining API for intricate URL modifications that can be cumbersome with standard string methods or even native APIs for older browser targets.","status":"maintenance","version":"1.19.11","language":"javascript","source_language":"en","source_url":"https://github.com/medialize/URI.js","tags":["javascript","uri","url","urn","uri mutation","url mutation","uri manipulation","url manipulation","uri template"],"install":[{"cmd":"npm install urijs","lang":"bash","label":"npm"},{"cmd":"yarn add urijs","lang":"bash","label":"yarn"},{"cmd":"pnpm add urijs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The npm package name is `urijs`, not `uri.js`. While CommonJS `require` still works, modern projects should prefer ESM `import`.","wrong":"const URI = require('uri.js');","symbol":"URI","correct":"import URI from 'urijs';"},{"note":"This is the standard CommonJS import for Node.js environments.","symbol":"URI","correct":"const URI = require('urijs');"},{"note":"Optional modules like `URITemplate` are typically imported from their specific paths within the package, not as named exports from the root.","wrong":"import { URITemplate } from 'urijs';","symbol":"URITemplate","correct":"import URITemplate from 'urijs/src/URITemplate';"}],"quickstart":{"code":"import URI from 'urijs';\n\nconst originalUrl = \"http://example.org/foo.html?hello=world\";\n\n// Create a new URI object\nconst url = new URI(originalUrl);\n\n// Perform a series of fluent manipulations\nconst modifiedUrl = url\n  .username(\"rodneyrehm\") // Add a username\n  .directory(\"bar\")     // Change directory segment\n  .suffix(\"xml\")      // Change file extension\n  .query({ foo: \"bar\", hello: [\"world\", \"mars\"] }) // Set multiple query parameters\n  .tld(\"com\");          // Change top-level domain\n\nconsole.log(`Original URL: ${originalUrl}`);\nconsole.log(`Modified URL: ${modifiedUrl.toString()}`);\n\n// Example of cleaning up query strings\nconst messyQueryUrl = URI(\"?&foo=bar&&foo=bar&foo=baz&\").normalizeQuery();\nconsole.log(`Cleaned Query: ${messyQueryUrl.toString()}`);\n\n// Example of URI Templates\nconst expandedUri = URI.expand(\"/foo/{dir}/{file}\", {\n  dir: \"bar\",\n  file: \"world.html\"\n});\nconsole.log(`Expanded URI: ${expandedUri}`);\n","lang":"javascript","description":"Demonstrates core URI object instantiation, fluent method chaining for URL mutation, query string normalization, and URI template expansion."},"warnings":[{"fix":"For new projects or modern environments, consider using `new URL()` and `new URLSearchParams()` for URL manipulation. Example:\n`const url = new URL('http://example.com?a=1'); url.searchParams.set('b', '2');`","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.19.3"},{"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.","message":"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__`.","severity":"breaking","affected_versions":">=1.19.7"},{"fix":"Always use `npm install urijs` and `require('urijs')` or `import URI from 'urijs';`.","message":"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.","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":"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.","cause":"The URI.js library was not correctly imported or required in the current scope.","error":"ReferenceError: URI is not defined"},{"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';`.","cause":"Incorrect package name used in `require()` or `import` statement, or an optional module path is wrong.","error":"Error: Cannot find module 'uri.js' (or 'urijs/src/URITemplate')"},{"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.","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.","error":"URL parsing yields unexpected segments (e.g., path, authority, query string appears malformed)"}],"ecosystem":"npm"}