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>