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://rodneyrehm@example.org/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:
-
RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
-
{RFC 2368 - The
mailto:
URL Scheme}[https://www.ietf.org/rfc/rfc2368.txt] -
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
Informal stuff
How other environments do things
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¶ ↑
-
mediawiki Uri (needs mw and jQuery)
URL Parsers¶ ↑
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
Various¶ ↑
-
TLD.js - second level domain names
-
Public Suffix - second level domain names
-
uri-collection - underscore based utility for working with many URIs
Authors¶ ↑
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