TypeScript icon, indicating that this package has built-in type declarations

    0.3.4 • Public • Published

    native-url npm package version bundle size github license

    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>


    npm i native-url

    DownloadsWeekly Downloads






    Unpacked Size

    94.7 kB

    Total Files


    Last publish


    • janicklas-ralph