{"id":11807,"library":"react-native-url-polyfill","title":"React Native URL Polyfill","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/charpeni/react-native-url-polyfill","tags":["javascript","URL","URLSearchParams","polyfill","react native","whatwg-url","typescript"],"install":[{"cmd":"npm install react-native-url-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-url-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-url-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native environment, required for core functionality.","package":"react-native","optional":false}],"imports":[{"note":"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.","wrong":"require('react-native-url-polyfill/auto');","symbol":"auto-polyfill","correct":"import 'react-native-url-polyfill/auto';"},{"note":"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.","wrong":"import URL from 'react-native-url-polyfill'; // Incorrect default export","symbol":"URL","correct":"import { URL, URLSearchParams } from 'react-native-url-polyfill';"},{"note":"The `URL.canParse()` static method was introduced in v3.0.0. After applying the polyfill, it becomes available globally.","symbol":"URL.canParse","correct":"import 'react-native-url-polyfill/auto';\nURL.canParse('https://example.com');"}],"quickstart":{"code":"import 'react-native-url-polyfill/auto';\nimport { useEffect, useState } from 'react';\nimport { Text, View, StyleSheet } from 'react-native';\n\nconst App = () => {\n  const [parsedUrl, setParsedUrl] = useState('');\n  const [searchParam, setSearchParam] = useState('');\n  const [canParseResult, setCanParseResult] = useState('');\n\n  useEffect(() => {\n    const urlString = 'https://www.example.com/path?query=value&id=123#fragment';\n    try {\n      const url = new URL(urlString);\n      setParsedUrl(`Origin: ${url.origin}, Host: ${url.host}, Path: ${url.pathname}`);\n      setSearchParam(`Query 'id': ${url.searchParams.get('id')}`);\n\n      // Test URL.canParse (introduced in v3.0.0)\n      const validParse = URL.canParse(urlString);\n      const invalidParse = URL.canParse('invalid-url');\n      setCanParseResult(`Can parse valid URL: ${validParse}, Can parse invalid URL: ${invalidParse}`);\n\n    } catch (e) {\n      setParsedUrl(`Error parsing URL: ${e.message}`);\n    }\n  }, []);\n\n  return (\n    <View style={styles.container}>\n      <Text style={styles.title}>react-native-url-polyfill Demo</Text>\n      <Text style={styles.text}>Original URL: https://www.example.com/path?query=value&id=123#fragment</Text>\n      <Text style={styles.text}>Parsed URL Info: {parsedUrl}</Text>\n      <Text style={styles.text}>Search Param Info: {searchParam}</Text>\n      <Text style={styles.text}>URL.canParse Result: {canParseResult}</Text>\n    </View>\n  );\n};\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20,\n    backgroundColor: '#f5fcff',\n  },\n  title: {\n    fontSize: 20,\n    fontWeight: 'bold',\n    marginBottom: 10,\n  },\n  text: {\n    fontSize: 16,\n    marginBottom: 5,\n    textAlign: 'center',\n  },\n});\n\nexport default App;\n","lang":"typescript","description":"This quickstart demonstrates how to apply the URL polyfill and use `URL`, `URLSearchParams`, and the static method `URL.canParse()` in a React Native component."},"warnings":[{"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.","message":"Despite 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"An 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.","severity":"gotcha","affected_versions":"<1.1.2"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: URLSearchParams.get is not implemented, js engine: hermes"},{"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`.","cause":"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.","error":"TypeError: URL.canParse is not a function"},{"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.","cause":"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.","error":"URL cannot handle \"localhost\" domain for base url"}],"ecosystem":"npm"}