https://github.com/charpeni/react-native-url-polyfill

🔗A lightweight and trustworthy URL polyfill for React Native.
https://github.com/charpeni/react-native-url-polyfill

javascript polyfill react-native url urlsearchparams whatwg-url

Last synced: 6 days ago
JSON representation

🔗A lightweight and trustworthy URL polyfill for React Native.

• Host: GitHub
• URL: https://github.com/charpeni/react-native-url-polyfill
• Owner: charpeni
• License: mit
• Created: 2019-11-22T04:28:41.000Z (about 5 years ago)
• Default Branch: main
• Last Pushed: 2023-12-23T19:07:56.000Z (12 months ago)
• Last Synced: 2024-11-28T03:20:01.591Z (15 days ago)
• Topics: javascript, polyfill, react-native, url, urlsearchparams, whatwg-url
• Language: Java
• Homepage:
• Size: 2.88 MB
• Stars: 346
• Watchers: 3
• Forks: 17
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-react-native - react-native-url-polyfill - 🔗A lightweight and trustworthy URL polyfill for React Native.  (Utilities)

README

        


  





  React Native URL Polyfill





  A lightweight and trustworthy URL polyfill for React Native





  

    

  

  

    

  

  

    

  

  

    

  

  

    

  





react-native-url-polyfill is an implementation of the WHATWG [URL Standard](https://url.spec.whatwg.org/) optimized for React Native.

- **Lightweight**. Uses a forked version of [`whatwg-url`](https://github.com/jsdom/whatwg-url) ([`whatwg-url-without-unicode`](https://github.com/charpeni/whatwg-url)) where unicode support has been stripped out — Going down from [372 KB](https://bundlephobia.com/[email protected]) to [40.9 KB](https://bundlephobia.com/[email protected]).

- **Trustworthy**. Follows closely the URL Standard spec, and relys on unit tests and Detox e2e tests within [React Native](https://github.com/facebook/react-native).

- **Blob support**. Supports React Native's Blob without additional steps.

- **Hermes support**. Supports [Hermes](https://github.com/facebook/hermes), a JavaScript engine optimized for running React Native.

- **Expo support**. Supports [Expo](https://expo.dev/) and tested against.

- **Web support**. Most of the time, this polyfill isn't useful on web and therefore using `react-native-url-polyfill/auto` will be no-op on web.

## Why do we need this?

React Native does include [a polyfill for `URL`](https://github.com/facebook/react-native/blob/8c0c860e38f57e18296f689e47dfb4a54088c260/Libraries/Blob/URL.js#L115-L222), but this polyfill is homemade — in order to keep it light-weight — and was initially created to handle specific use cases.

Meanwhile, React Native has grown around that polyfill, then some unexpected errors have arisen.

> Known issues (non-exhaustive) with React Native's URL are:

>

> - URL cannot handle "localhost" domain for base url [react-native#26019](https://github.com/facebook/react-native/issues/26019).

> - URL implementation should add a trailing slash to the base [react-native#25717](https://github.com/facebook/react-native/issues/25717).

> - URL incorrectly adds trailing slash [react-native#24428](https://github.com/facebook/react-native/issues/24428).

> - Creating an instance of URL like: `new URL('http://facebook.com')` throws an exception [react-native#16434](https://github.com/facebook/react-native/issues/16434).

That's why you may need this external dependency. So, if you use `URL` within your app, you probably want to take a look at the installation steps below!

Unfortunately, adding `react-native-url-polyfill` to React Native source code would mean adding 📦 **73.67 KB** (as of RN 0.72) to the JavaScript bundle, that's why it's not included by default.

## Installation

First, you need to install the polyfill, which can be done with [Yarn](https://yarnpkg.com/) or [npm](https://www.npmjs.com/).

#### Yarn

```bash

yarn add react-native-url-polyfill

```

#### npm

```bash

npm install --save react-native-url-polyfill

```

Then, the polyfill can be used in multiple ways. Pick your preferred option.

> ℹ️ To verify if the polyfill has been correctly applied, you can check if the global variable `REACT_NATIVE_URL_POLYFILL` contains the current package and version like: `react-native-url-polyfill@CURRENT_VERSION`.

### Option 1 (_Simple_)

Locate your JavaScript entry-point file, commonly called `index.js` at the root of your React Native project.

Then, import `react-native-url-polyfill/auto` at the top of your entry-point file, the polyfill will be automatically applied.

```javascript

import 'react-native-url-polyfill/auto';

```

### Option 2 (_Flexible_)

If you want to apply the polyfill when you're ready, you can import `setupURLPolyfill` and call it yourself.

> ⚠️ Metro doesn't support optional imports.

>

> If you do not apply the polyfill, it will still be added to your JavaScript bundle.

> Even if it's wrapped in a condition, Metro won't strip it in production.

```javascript

import { setupURLPolyfill } from 'react-native-url-polyfill';

setupURLPolyfill();

```

### Option 3 (_Convenient_ / ponyfill)

If you prefer not to apply this polyfill over React Native's default `URL`, you can still import those classes manually when you want them.

```javascript

import { URL, URLSearchParams } from 'react-native-url-polyfill';

const url = new URL('https://github.com');

const searchParams = new URLSearchParams('q=GitHub');

```

## License

react-native-url-polyfill is [MIT licensed](LICENSE).