Registry / http-networking / react-native-url-polyfill

react-native-url-polyfill

JSON →
library3.0.0jsnpmunverified

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-polyfill
INSTALL
IMPORT
SIG · REACT-NATIVE-URL-P
R
react-native-url-polyfill
http-networkingjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

auto-polyfill
import 'react-native-url-polyfill/auto';
require('react-native-url-polyfill/auto');
This import statement, typically placed at the entry point (e.g., `index.js`), automatically applies the polyfill globally for `URL` and `URLSearchParams`. This is the most common usage.
URL
import { URL, URLSearchParams } from 'react-native-url-polyfill';
import URL from 'react-native-url-polyfill'; // Incorrect default export
For explicit, non-global polyfilling or if you prefer to use the classes directly without polluting the global scope, you can import `URL` and `URLSearchParams` as named exports. This is less common than the `/auto` import. Ensure it's done *before* any code that relies on the polyfilled functionality.
URL.canParse
import 'react-native-url-polyfill/auto'; URL.canParse('https://example.com');
The `URL.canParse()` static method was introduced in v3.0.0. After applying the polyfill, it becomes available globally.

This quickstart demonstrates how to apply the URL polyfill and use `URL`, `URLSearchParams`, and the static method `URL.canParse()` in a React Native component.

import 'react-native-url-polyfill/auto'; import { useEffect, useState } from 'react'; import { Text, View, StyleSheet } from 'react-native'; const App = () => { const [parsedUrl, setParsedUrl] = useState(''); const [searchParam, setSearchParam] = useState(''); const [canParseResult, setCanParseResult] = useState(''); useEffect(() => { const urlString = 'https://www.example.com/path?query=value&id=123#fragment'; try { const url = new URL(urlString); setParsedUrl(`Origin: ${url.origin}, Host: ${url.host}, Path: ${url.pathname}`); setSearchParam(`Query 'id': ${url.searchParams.get('id')}`); // Test URL.canParse (introduced in v3.0.0) const validParse = URL.canParse(urlString); const invalidParse = URL.canParse('invalid-url'); setCanParseResult(`Can parse valid URL: ${validParse}, Can parse invalid URL: ${invalidParse}`); } catch (e) { setParsedUrl(`Error parsing URL: ${e.message}`); } }, []); return ( <View style={styles.container}> <Text style={styles.title}>react-native-url-polyfill Demo</Text> <Text style={styles.text}>Original URL: https://www.example.com/path?query=value&id=123#fragment</Text> <Text style={styles.text}>Parsed URL Info: {parsedUrl}</Text> <Text style={styles.text}>Search Param Info: {searchParam}</Text> <Text style={styles.text}>URL.canParse Result: {canParseResult}</Text> </View> ); }; const styles = StyleSheet.create({ container: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20, backgroundColor: '#f5fcff', }, title: { fontSize: 20, fontWeight: 'bold', marginBottom: 10, }, text: { fontSize: 16, marginBottom: 5, textAlign: 'center', }, }); export default App;
Debug
Known issues
gotchaDespite v2.0.0 being a major version, the release notes stated 'we don't expect any breaking changes. The upgrade should be seamless.' However, its behavior changed regarding `react-native-url-polyfill/auto` on web platforms (e.g., `react-native-web`), where it would previously apply the polyfill but now acts as a no-op. While not breaking *functionality* for React Native, it changes cross-platform polyfill application.
fix
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.
affects: >=2.0.0
breakingVersion 3.0.0 introduces `URL.canParse()`, which, while a standard Web API addition, might lead to issues in environments that do not inherently support it (like older React Native versions or certain test runners that don't polyfill it). This is more of a feature addition, but if you upgrade `react-native-url-polyfill` and your React Native environment's baseline is too old for the `URL` spec it polyfills, it *could* technically break if you try to use this specific feature without the polyfill being active.
fix
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.
affects: >=3.0.0
gotchaThe polyfill, by design, strips out Unicode support for hostnames to maintain a lightweight footprint on mobile devices. This means non-ASCII characters in the hostname portion of a URL are not supported and may lead to incorrect parsing or errors.
fix
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.
affects: >=1.0.0
gotchaAn incompatibility with the Hermes JavaScript engine was fixed in version 1.1.2. Older versions of the polyfill might exhibit unexpected behavior or errors when running on Hermes.
fix
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.
affects: <1.1.2
gotchaPrior to version 1.1.0, the package included `lodash.sortby` as a dependency, increasing its bundle size. This dependency was removed in v1.1.0 to reduce the package size by approximately 13 KB.
fix
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.
affects: <1.1.0
Errors
Common errors & fixes
TypeError: URLSearchParams.get is not implemented, js engine: hermes
The `URLSearchParams` API or specific methods like `get` are not fully implemented in React Native's default URL polyfill or an older version of `react-native-url-polyfill` is being used with Hermes.
fix
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.
TypeError: URL.canParse is not a function
The `URL.canParse()` static method was introduced in `react-native-url-polyfill` v3.0.0 and is not present in earlier versions or the global polyfill has not been applied correctly.
fix
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`.
URL cannot handle "localhost" domain for base url
This is a known issue with React Native's *native* URL implementation, which `react-native-url-polyfill` aims to address. It indicates the polyfill is either not active or not correctly overriding the native implementation.
fix
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.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
react-nativerequiredPeer dependency for React Native environment, required for core functionality.
Agent activity
6 hits · last 30 days
node
6
Resources
react-native-url-polyfill — npm install react-native-url-polyfill · libregistry