# portable-url

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

Latest version **0.3.6** (published 2021-12-20) · Apache-2.0 license · 0 weekly downloads

## Install

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

## Health

**Score 30/100 (F)** — status: abandoned.

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

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.6 |
| Published | 2021-12-20 |
| First published | 2021-12-20 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 98.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Janicklas Ralph |
| Maintainers | louisremi |
| Keywords | url, uri, normalization, normalisation, query, querystring, whatwg-url, parse, format, resolve, resolveObject |

## Links

- npm: https://www.npmjs.com/package/portable-url
- Repository: https://github.com/louisremi/portable-url
- Homepage: https://github.com/louisremi/portable-url#readme
- Issues: https://github.com/louisremi/portable-url/issues
- npm.io page: https://npm.io/package/portable-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.6 (latest) — 2021-12-20
- 0.3.5 — 2021-12-20

## README

# portable-url [![npm package version](https://badgen.net/npm/v/portable-url)](https://npm.im/portable-url) [![bundle size](https://badgen.net/bundlephobia/minzip/portable-url)](https://bundlephobia.com/result?p=portable-url) [![github license](https://badgen.net/github/license/GoogleChromeLabs/portable-url)](https://github.com/GoogleChromeLabs/portable-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.
This repo is an active fork of the original [native-url](https://github.com/GoogleChromeLabs/native-url) which has been inactive since June 20.

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 portable-url
```

## Usage

```js
const url = require('portable-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 `portable-url` instead, saving around 7.5kB:

```js
// webpack.config.js
module.exports = {
  // ...
  resolve: {
    alias: {
      url: 'portable-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 `portable-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: 'portable-url',
      },
    }),
  ],
};
```

With this in place, `import url from 'url'` will use `portable-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

`portable-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/portable-url · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._