urijs

What is urijs?

The urijs (also known as URI.js) package is a versatile library for working with URLs. It provides utilities for parsing, manipulating, and building URIs in a fluent API style. This makes it easier to handle various components of URIs such as protocol, hostname, path, query, and fragment.

What are urijs's main functionalities?

Parsing URIs

This feature allows for parsing URIs and accessing their different components like protocol, hostname, etc. The example demonstrates how to parse a URI and retrieve the protocol component.

const URI = require('urijs');
const uri = URI('http://example.com/foo?bar=baz');
console.log(uri.protocol()); // 'http'

Manipulating URIs

This feature enables modification of various URI components. The example shows how to change the path segment of a URI.

const URI = require('urijs');
const uri = URI('http://example.com/foo');
const newUri = uri.segment('bar').toString();
console.log(newUri); // 'http://example.com/bar'

Building URIs

This feature is useful for constructing URIs from scratch by chaining methods to set different URI components. The example constructs a complete URI from individual components.

const URI = require('urijs');
const uri = URI().protocol('http').hostname('example.com').path('/foo').query({ bar: 'baz' }).toString();
console.log(uri); // 'http://example.com/foo?bar=baz'

Other packages similar to urijs

url-parse

url-parse is another npm package that offers similar functionalities for parsing and manipulating URLs. It provides a more straightforward API for parsing URLs and can handle relative URLs better than urijs. However, urijs offers more fluent and versatile URI manipulation capabilities.

qs

While primarily focused on parsing and stringifying query strings, qs can be used in conjunction with other URL manipulation libraries to provide functionality similar to urijs. It does not handle full URI components but is very efficient for query string operations compared to urijs's broader URL handling features.

README

URI.js

• About
• Understanding URIs
• Documentation
• jQuery URI Plugin
• Author
• Changelog

---

IMPORTANT: You may not need URI.js anymore! Modern browsers provide the URL and URLSearchParams interfaces.

---

NOTE: The npm package name changed to urijs

---

I always want to shoot myself in the head when looking at code like the following:

var url = "http://example.org/foo?bar=baz";
var separator = url.indexOf('?') > -1 ? '&' : '?';

url += separator + encodeURIComponent("foo") + "=" + encodeURIComponent("bar");

Things are looking up with URL and the URL spec but until we can safely rely on that API, have a look at URI.js for a clean and simple API for mutating URIs:

var url = new URI("http://example.org/foo?bar=baz");
url.addQuery("foo", "bar");

URI.js is here to help with that.

API Example

// mutating URLs
URI("http://example.org/foo.html?hello=world")
  .username("rodneyrehm")
    // -> http://[e-mail]/foo.html?hello=world
  .username("")
    // -> http://example.org/foo.html?hello=world
  .directory("bar")
    // -> http://example.org/bar/foo.html?hello=world
  .suffix("xml")
    // -> http://example.org/bar/foo.xml?hello=world
  .query("")
    // -> http://example.org/bar/foo.xml
  .tld("com")
    // -> http://example.com/bar/foo.xml
  .query({ foo: "bar", hello: ["world", "mars"] });
    // -> http://example.com/bar/foo.xml?foo=bar&hello=world&hello=mars

// cleaning things up
URI("?&foo=bar&&foo=bar&foo=baz&")
  .normalizeQuery();
    // -> ?foo=bar&foo=baz

// working with relative paths
URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/world.html");
    // -> ./baz.html

URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/sub/world.html")
    // -> ../baz.html
  .absoluteTo("/foo/bar/sub/world.html");
    // -> /foo/bar/baz.html

// URI Templates
URI.expand("/foo/{dir}/{file}", {
  dir: "bar",
  file: "world.html"
});
// -> /foo/bar/world.html

See the About Page and API Docs for more stuff.

Using URI.js

URI.js (without plugins) has a gzipped weight of about 7KB - if you include all extensions you end up at about 13KB. So unless you need second level domain support and use URI templates, we suggest you don't include them in your build. If you don't need a full featured URI mangler, it may be worth looking into the much smaller parser-only alternatives listed below.

URI.js is available through npm, bower, bowercdn, cdnjs and manually from the build page:

# using bower
bower install uri.js

# using npm
npm install urijs

Browser

I guess you'll manage to use the build tool or follow the instructions below to combine and minify the various files into URI.min.js - and I'm fairly certain you know how to <script src=".../URI.min.js"></script> that sucker, too.

Node.js and NPM

Install with npm install urijs or add "urijs" to the dependencies in your package.json.

// load URI.js
var URI = require('urijs');
// load an optional module (e.g. URITemplate)
var URITemplate = require('urijs/src/URITemplate');

URI("/foo/bar/baz.html")
  .relativeTo("/foo/bar/sub/world.html")
    // -> ../baz.html

RequireJS

Clone the URI.js repository or use a package manager to get URI.js into your project.

require.config({
  paths: {
    urijs: 'where-you-put-uri.js/src'
  }
});

require(['urijs/URI'], function(URI) {
  console.log("URI.js and dependencies: ", URI("//amazon.co.uk").is('sld') ? 'loaded' : 'failed');
});
require(['urijs/URITemplate'], function(URITemplate) {
  console.log("URITemplate.js and dependencies: ", URITemplate._cache ? 'loaded' : 'failed');
});

Minify

See the build tool or use Google Closure Compiler:

// ==ClosureCompiler==
// @compilation_level SIMPLE_OPTIMIZATIONS
// @output_file_name URI.min.js
// @code_url http://medialize.github.io/URI.js/src/IPv6.js
// @code_url http://medialize.github.io/URI.js/src/punycode.js
// @code_url http://medialize.github.io/URI.js/src/SecondLevelDomains.js
// @code_url http://medialize.github.io/URI.js/src/URI.js
// @code_url http://medialize.github.io/URI.js/src/URITemplate.js
// ==/ClosureCompiler==

Resources

Documents specifying how URLs work:

• URL - Living Standard
• RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
• RFC 3987 - Internationalized Resource Identifiers (IRI)
• RFC 2732 - Format for Literal IPv6 Addresses in URL's
• RFC 2368 - The mailto: URL Scheme
• RFC 2141 - URN Syntax
• IANA URN Namespace Registry
• Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA)
• application/x-www-form-urlencoded (Query String Parameters) and application/x-www-form-urlencoded encoding algorithm
• What every web developer must know about URL encoding

Informal stuff

• Parsing URLs for Fun and Profit
• Naming URL components

How other environments do things

• Java URI Class
• Java Inet6Address Class
• Node.js URL API

Discussion on Hacker News

Forks / Code-borrow

• node-dom-urls passy's partial implementation of the W3C URL Spec Draft for Node
• urlutils cofounders' window.URL constructor for Node

Alternatives

If you don't like URI.js, you may like one of the following libraries. (If yours is not listed, drop me a line…)

Polyfill

• DOM-URL-Polyfill arv's polyfill of the DOM URL spec for browsers
• inexorabletash inexorabletash's WHATWG URL API

URL Manipulation

• The simple URL Mutation "Hack" (jsPerf comparison)
• URL.js
• furl (Python)
• mediawiki Uri (needs mw and jQuery)
• jurlp
• jsUri

URL Parsers

• The simple URL Mutation "Hack" (jsPerf comparison)
• URI Parser
• jQuery-URL-Parser
• Google Closure Uri
• URI.js by Gary Court

URI Template

• uri-template (supporting extraction as well) by Rezigne
• uri-templates (supporting extraction as well) by Geraint Luff
• uri-templates by Marc Portier
• uri-templates by Geraint Luff (including reverse operation)
• URI Template JS by Franz Antesberger
• Temple by Brett Stimmerman
• (jsperf comparison)

Various

• TLD.js - second level domain names
• Public Suffix - second level domain names
• uri-collection - underscore based utility for working with many URIs

Authors

• Rodney Rehm
• Various Contributors

Contains Code From

• punycode.js - Mathias Bynens
• IPv6.js - Rich Brown - (rewrite of the original)

License

URI.js is published under the MIT license. Until version 1.13.2 URI.js was also published under the GPL v3 license - but as this dual-licensing causes more questions than helps anyone, it was dropped with version 1.14.0.

Changelog

moved to Changelog

Changelog

1.19.11 (April 3rd 2022) ###

• SECURITY fixing URI.parse() handle excessive slashes in scheme-relative URLs - disclosed by zeyu2001 via https://huntr.dev/
• SECURITY fixing URI.parse() remove \r (CR), \n, (LF) \t (TAB) - disclosed by haxatron via https://huntr.dev/