React Native URL Polyfill

A lightweight and trustworthy URL polyfill for React Native, based on the WHATWG URL Standard optimized for React Native.

• Lightweight. Uses a forked version of whatwg-url (whatwg-url-without-unicode) where Unicode support has been stripped out—Going down from 372 KB to 40.9 KB.
• Trustworthy. Follows the URL Standard spec, and relies on unit tests and Detox e2e tests within React Native.
• Blob support. Supports React Native's Blob without additional steps.
• Hermes support. Supports Hermes, a JavaScript engine optimized for running React Native.
• Expo support. Supports Expo.
• 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.

[!IMPORTANT] As mentioned above, Unicode support has been stripped out to keep this polyfill lightweight on mobile. Therefore, non-ASCII characters aren't supported in the hostname.

Why do we need this?

React Native does include a polyfill for URL, 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.

[!NOTE] Known issues (non-exhaustive) with React Native's URL are:

• URL cannot handle "localhost" domain for base url react-native#26019.
• URL implementation should add a trailing slash to the base react-native#25717.
• URL incorrectly adds trailing slash react-native#24428.
• Creating an instance of URL like: new URL('http://facebook.com') throws an exception react-native#16434.

That's why you may need this external dependency. If you use URL within your app, you should look at the installation steps below!

Unfortunately, adding react-native-url-polyfill to React Native source code would mean adding 📦 73.9 KB (as of RN 0.81) 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, npm, and others.

yarn add react-native-url-polyfill

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

[!TIP] 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.

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.

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.

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.