react-native-url-polyfill is a lightweight and robust polyfill for the WHATWG URL Standard, specifically optimized for React Native environments. It addresses limitations and inconsistencies in React Native's built-in URL implementation, which can lead to unexpected errors with complex URL parsing or specific properties like `searchParams` and `hostname`. The current stable version is 3.0.0. While there isn't a fixed monthly cadence, the project actively releases major versions for significant updates like new Web API features (e.g., `URL.canParse()`) and minor/patch versions for bug fixes and compatibility improvements. Key differentiators include its lightweight nature (stripping Unicode support to reduce bundle size to ~40KB, down from 372KB for the full `whatwg-url` package), trustworthiness (following the spec, backed by unit and Detox e2e tests), and explicit support for Hermes, Expo, and Blob objects.
npm install react-native-url-polyfillVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to apply the URL polyfill and use `URL`, `URLSearchParams`, and the static method `URL.canParse()` in a React Native component.
If explicitly relying on this polyfill for web (e.g., `react-native-web`), ensure to test its functionality after upgrading to v2.0.0+ as it will no longer polyfill on web when using `/auto`. Consider conditional imports or native browser URL APIs for web-specific contexts if the polyfill's behavior is critical.
Ensure `react-native-url-polyfill/auto` is imported at your application's entry point to guarantee `URL.canParse()` is polyfilled. Verify compatibility with your target React Native version. If using Jest, ensure your Jest setup or `jest-environment-jsdom` is configured to correctly provide the WHATWG URL API.
Avoid using non-ASCII characters in the hostname part of URLs when relying on this polyfill. If internationalized domain names (IDNs) are critical, consider pre-processing URLs with a library that handles Punycode encoding/decoding before passing them to the URL constructor, or evaluate alternative polyfills with full Unicode support if bundle size is not a primary concern.
Upgrade to `react-native-url-polyfill` version 1.1.2 or higher to ensure full compatibility and stability when using the Hermes engine in React Native applications.
Upgrade to `react-native-url-polyfill` version 1.1.0 or higher to benefit from the reduced bundle size and improved performance due to the removal of unnecessary `lodash` dependency.
Ensure you have `react-native-url-polyfill` installed and `import 'react-native-url-polyfill/auto';` is placed at the very top of your application's entry file (e.g., `index.js`). Also, update to version 1.1.2 or newer for better Hermes compatibility.
Upgrade `react-native-url-polyfill` to version 3.0.0 or higher. Confirm that `import 'react-native-url-polyfill/auto';` is correctly placed at the application entry point to ensure the global `URL` object is extended with `canParse`.
Double-check that `import 'react-native-url-polyfill/auto';` is the very first import in your main React Native entry file (e.g., `index.js` or `App.js`) to ensure it applies before other code uses the `URL` object.