url-join

What is url-join?

The url-join npm package is a utility for joining and normalizing URLs. It is particularly useful when constructing URLs dynamically, ensuring that the resulting URL is correctly formatted without duplicated slashes or missing segments. This package can handle various scenarios, including joining multiple parts of a URL, handling query strings, and ensuring the correct inclusion of protocols.

What are url-join's main functionalities?

Joining URL segments

This feature allows for the concatenation of multiple segments into a single, well-formed URL. It automatically handles the insertion or removal of slashes as needed between segments.

"const urlJoin = require('url-join');\nconst fullUrl = urlJoin('http://example.com', 'a', '/b/cd', '?foo=123');\nconsole.log(fullUrl); // Outputs: http://example.com/a/b/cd?foo=123"

Handling trailing slashes

This feature ensures that trailing slashes are correctly handled, either preserving them or removing them based on the input segments, thus maintaining the intended URL structure.

"const urlJoin = require('url-join');\nconst fullUrl = urlJoin('http://example.com/', '/a/b/', '/');\nconsole.log(fullUrl); // Outputs: http://example.com/a/b/"

Combining URL with query parameters

This feature demonstrates how url-join can be used to append query parameters to a base URL, ensuring that the '?' character is correctly placed and that the overall URL remains well-formed.

"const urlJoin = require('url-join');\nconst fullUrl = urlJoin('http://example.com', 'search', '?q=url+join');\nconsole.log(fullUrl); // Outputs: http://example.com/search?q=url+join"

Other packages similar to url-join

path-to-regexp

While primarily focused on converting paths to regex, path-to-regexp can be used to construct URLs in a more controlled manner. It differs from url-join by offering more complex pattern matching and parameter handling, making it more suitable for routing purposes rather than simple URL concatenation.

urijs

URI.js is a more comprehensive URL manipulation library that offers functionality similar to url-join but extends far beyond it. It includes parsing, manipulation, and normalization of URLs, query string manipulation, and much more. Compared to url-join, URI.js is better suited for applications requiring extensive URL manipulation capabilities.

README

Join all arguments together and normalize the resulting url.

Install

npm install url-join

Usage

var urljoin = require('url-join');

var fullUrl = urljoin('http://www.google.com', 'a', '/b/cd', '?foo=123');

console.log(fullUrl);

Prints:

'http://www.google.com/a/b/cd?foo=123'

Browser and AMD

It also works in the browser, you can either include lib/url-join.js in your page:

<script src="url-join.js"></script>
<script type="text/javascript">
	urljoin('http://blabla.com', 'foo?a=1')
</script>

Or using an AMD module system like requirejs:

define(['path/url-join.js'], function (urljoin) {
  urljoin('http://blabla.com', 'foo?a=1');
});

License

MIT

Changelog

3.0.0 - 2018-01-12

• add new test (d65d7c1696cb53b53ceabadf1a77917196967b4c)
• Fixed to handle the colon in non-protocol separation role in the first part. (9212db75f805031a9cc06120b5dd08a6cdd805e4)