Join all arguments together and normalize the resulting URL.

npm install url-join

If you want to use it directly in a browser use a CDN like Skypack.

import urlJoin from 'url-join';

const fullUrl = urlJoin('http://www.google.com', 'a', '/b/cd', '?foo=123', '&bar=456', '#heading-1');

console.log(fullUrl.toString()); // 'http://www.google.com/a/b/cd?foo=123&bar=456#heading-1'

This library was originally created before the URL API was standardized and widely available in popular runtimes such as browsers and Node.js. Depending on your use-case you might want to consider using the standardized API over this library.

For example, the equivalent code for the above example would look as follows when using the URL API:

const fullUrl = new URL('http://www.google.com');

fullUrl.pathname = '/a/b/cd';
fullUrl.searchParams.append('foo', '123');
fullUrl.searchParams.append('bar', '456');
fullUrl.hash = 'heading-1';

console.log(fullUrl.toString()); // 'http://www.google.com/a/b/cd?foo=123&bar=456#heading-1'

This library provides the missing piece for the URL API, joining multiple paths together:

import urlJoin from 'url-join';

const fullUrl = new URL('http://www.google.com');

fullUrl.pathname = urlJoin('a', '/b/cd');

console.log(fullUrl.toString()); // 'http://www.google.com/a/b/cd'

If you are using Node.js, the path/posix module can join paths in a way that is compatible with URL pathnames:

import { join as joinPath } from 'node:path/posix';

const fullUrl = new URL('http://www.google.com');

fullUrl.pathname = joinPath('a', '/b/cd');

console.log(fullUrl.toString()); // 'http://www.google.com/a/b/cd'

There are a couple of caveats to take into account when utilizing the standard APIs. Firstly, a URL must always include a complete and valid base, which means specifying the scheme and domain name (e.g. http://example.com).

Secondly, it is not possible to join together and normalize the path of a URL. You must do this manually by joining your paths and then assigning the pathname property.

MIT