native-url

native-url

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:

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

Installation

npm i native-url

Usage

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

url.parse('https://example.com').host; // example.com
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: [
    resolve(),
    alias({
      entries: {
        url: 'native-url',
      },
    }),
  ],
};

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

API

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:

url.parse('https://example.com');
// {
//   href: 'http://example.com/',
//   protocol: 'http:',
//   slashes: true,
//   host: 'example.com',
//   hostname: 'example.com',
//   query: {},
//   search: null,
//   pathname: '/',
//   path: '/'
// }

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

url.format(urlObj)

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

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

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>