https://github.com/GoogleChromeLabs/native-url

Node's url module implemented using the built-in URL API.
https://github.com/GoogleChromeLabs/native-url

nodejs querystring url url-parser

Last synced: 3 months ago
JSON representation

Node's url module implemented using the built-in URL API.

• Host: GitHub
• URL: https://github.com/GoogleChromeLabs/native-url
• Owner: GoogleChromeLabs
• License: apache-2.0
• Created: 2019-10-21T20:50:27.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2024-03-14T19:46:46.000Z (11 months ago)
• Last Synced: 2024-05-15T23:48:14.989Z (9 months ago)
• Topics: nodejs, querystring, url, url-parser
• Language: JavaScript
• Homepage: https://npm.im/native-url
• Size: 1.63 MB
• Stars: 285
• Watchers: 7
• Forks: 11
• Open Issues: 19
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-nodejs - native-url - Node's url module implemented using the built-in URL API.  (Repository / URL)
• awesome-list - native-url - in URL API. | GoogleChromeLabs | 279 | (JavaScript)

README

        
# native-url [![npm package version](https://badgen.net/npm/v/native-url)](https://npm.im/native-url) [![bundle size](https://badgen.net/bundlephobia/minzip/native-url)](https://bundlephobia.com/result?p=native-url) [![github license](https://badgen.net/github/license/GoogleChromeLabs/native-url)](https://github.com/GoogleChromeLabs/native-url/blob/master/LICENSE)

A lightweight implementation of Node's [url](http://nodejs.org/api/url.html) interface atop the [URL API](https://developer.mozilla.org/en-US/docs/Web/API/URL). 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](https://caniuse.com/#feat=mdn-api_url):

![Chrome 32, Firefox 19, Safari 7, Edge 12, Opera 19](https://badges.herokuapp.com/browsers?googlechrome=32&firefox=19&safari=7&microsoftedge=12&opera=19)

Older browsers can be [easily polyfilled](#polyfill-for-older-browsers) without new browsers loading the code.

## Installation

```sh

npm i native-url

```

## Usage

```js

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`](https://github.com/defunctzombie/node-url) for the browser. You can alias webpack to use `native-url` instead, saving around 7.5kB:

```js

// 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:

```js

// 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](https://nodejs.org/api/url.html#url_legacy_url_api) for detailed API documentation.

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

Parses a URL string and returns a URL object representation:

```js

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:

```js

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

// "https://example.com"

```

### `url.resolve(from, to)`

Resolves a target URL based on the provided base URL:

```js

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](https://developer.mozilla.org/en-US/docs/Web/API/URL) to work. For older browsers that don't support the `URL` API, a [polyfill](https://www.npmjs.com/package/url-polyfill) is available.

Conveniently, a polyfill is never needed for [browsers that support ES Modules](https://caniuse.com/#feat=es6-module), so we can use `` to conditionally load it for older browsers:

```html

<script nomodule src="/path/to/url-polyfill.js">

```