Skip to content
Node's url module implemented using the built-in URL API.
Branch: master
Clone or download
Latest commit 8c9cd74 Nov 13, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Repo setup Oct 21, 2019
src Restructuring exports to avoid default key Oct 23, 2019
third_party Restructuring exports to avoid default key Oct 23, 2019
.gitignore Repo setup Oct 21, 2019
.prettierrc Repo setup Oct 21, 2019 Repo setup Oct 21, 2019
LICENSE Repo setup Oct 21, 2019 Update Nov 7, 2019
index.d.ts use @types/node for typings Nov 9, 2019
package.json Release 0.2.1 Nov 13, 2019
yarn.lock use @types/node for typings Nov 9, 2019


A lightweight implementation of Node's url interface atop the URL API. Use it instead of the url module to reduce your bundle size by around 7.5 kB.

Weighs 1.6 kB gzipped, works in Node.js 7+ and all modern browsers:

Chrome 32, Firefox 19, Safari 7, Edge 12, Opera 19

Older browsers can be easily polyfilled without new browsers loading the code.


npm i native-url


const url = require('native-url');

url.parse('').host //
url.parse('/?a=b', true).query // { a: 'b' }

Usage with Webpack

When you use the url module, webpack bundles node-url for the browser. You can alias webpack to use native-url instead, saving around 7.5kB:

// webpack.config.js
module.exports = {
  // ...
  resolve: {
    alias: {
      url: 'native-url'

The result is functionally equivalent in Node 7+ and all modern browsers.

Usage with Rollup

Rollup does not bundle shims for Node.js modules like url by default, but we can add url support via native-url using aliases:

// rollup.config.js
import resolve from 'rollup-plugin-node-resolve';
import alias from '@rollup/plugin-alias';

module.exports = {
  // ...
  plugins: [
      entries: {
        url: 'native-url'

With this in place, import url from 'url' will use native-url and keep your bundle small.


Refer Node's legacy url documentation for detailed API documentation.

url.parse(urlStr, [parseQueryString], [slashesDenoteHost])

Parses a URL string and returns a URL object representation:

// {
//   href: '',
//   protocol: 'http:',
//   slashes: true,
//   host: '',
//   hostname: '',
//   query: {},
//   search: null,
//   pathname: '/',
//   path: '/'
// }

url.parse('/foo?a=b', true).query.a; // "b"


Given a parsed URL object, returns its corresponding URL string representation:

url.format({ protocol: 'https', host: '' });
// ""

url.resolve(from, to)

Resolves a target URL based on the provided base URL:

url.resolve('/a/b', 'c');
// "/a/b/c"
url.resolve('/a/b', '/c#d');
// "/c#d"

Polyfill for Older Browsers

native-url relies on the DOM URL API to work. For older browsers that don't support the URL API, a polyfill is available.

Conveniently, a polyfill is never needed for browsers that support ES Modules, so we can use <script nomodule> to conditionally load it for older browsers:

<script nomodule src="/path/to/url-polyfill.js"></script>
You can’t perform that action at this time.