react-native-url-polyfill

What is react-native-url-polyfill?

The react-native-url-polyfill package provides a polyfill for the URL and URLSearchParams classes in React Native environments. This is particularly useful for ensuring compatibility with web standards and APIs that rely on these classes.

What are react-native-url-polyfill's main functionalities?

URL Polyfill

This feature provides a polyfill for the URL class, allowing you to create and manipulate URL objects in a React Native environment just as you would in a web browser.

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

const url = new URL('https://example.com/path?name=ReactNative');
console.log(url.hostname); // 'example.com'
console.log(url.pathname); // '/path'
console.log(url.searchParams.get('name')); // 'ReactNative'

URLSearchParams Polyfill

This feature provides a polyfill for the URLSearchParams class, enabling you to work with query string parameters in a React Native environment.

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

const params = new URLSearchParams('name=ReactNative&version=0.64');
console.log(params.get('name')); // 'ReactNative'
console.log(params.get('version')); // '0.64'
params.append('platform', 'iOS');
console.log(params.toString()); // 'name=ReactNative&version=0.64&platform=iOS'

Other packages similar to react-native-url-polyfill

whatwg-url

The whatwg-url package is a full implementation of the WHATWG URL Standard, which is used in many web browsers. It provides similar functionality to react-native-url-polyfill but is more comprehensive and can be used in both Node.js and browser environments. However, it may require additional configuration to work seamlessly in React Native.

url-polyfill

The url-polyfill package provides a polyfill for the URL and URLSearchParams classes, similar to react-native-url-polyfill. It is designed to work in environments that do not natively support these classes, such as older browsers. While it can be used in React Native, it is not specifically tailored for that environment.

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 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 closely the URL Standard spec, and relys 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 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, 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.
• 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. 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 or npm.

Yarn

yarn add react-native-url-polyfill

npm

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.

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.

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.