# native-url

> Brings the node url api layer to whatwg-url class

Latest version **0.3.4** (published 2020-06-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install native-url
pnpm add native-url
yarn add native-url
bun add native-url
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.3.4 |
| Published | 2020-06-29 |
| First published | 2019-09-23 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 92.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 286 |
| Author | Janicklas Ralph |
| Maintainers | janicklas-ralph |
| Keywords | url, uri, normalization, normalisation, query, querystring, whatwg-url, parse, format, resolve, resolveObject |

## Links

- npm: https://www.npmjs.com/package/native-url
- Repository: https://github.com/GoogleChromeLabs/native-url
- Homepage: https://github.com/GoogleChromeLabs/native-url#readme
- Issues: https://github.com/GoogleChromeLabs/native-url/issues
- npm.io page: https://npm.io/package/native-url

## Dependencies (1)

- [querystring](https://npm.io/package/querystring.md) ^0.2.0

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 0.3.4 (latest) — 2020-06-29
- 0.3.3 — 2020-06-24
- 0.3.2 — 2020-06-05
- 0.3.1 — 2020-04-05
- 0.3.0 — 2020-04-04
- 0.2.6 — 2020-01-29
- 0.2.5 — 2020-01-24
- 0.2.4 — 2019-12-16
- 0.2.3 — 2019-11-27
- 0.2.2 — 2019-11-26
- 0.2.1 — 2019-11-13
- 0.2.0 — 2019-10-24
- 0.1.2 — 2019-10-21
- 0.1.1 — 2019-09-23
- 0.1.0 — 2019-09-23

## 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 `<script nomodule>` to conditionally load it for older browsers:

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

---
_Source: https://npm.io/package/native-url · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._