What does react-native-url-polyfill/auto do, and do I still need it?

If you’ve copied a Supabase setup into a React Native app, you’ve probably seen import 'react-native-url-polyfill/auto' on the first line and wondered whether it does anything. It does one small job at a small cost, and in a Supabase app it’s worth keeping.

What it does

JavaScript code uses the URL class to read the parts of a web address (the protocol, the hostname, the path, the query) and URLSearchParams to read and build query strings. Browsers and Node.js include full versions of both, while React Native includes its own simpler ones. A polyfill is a replacement for a built-in that’s missing or incomplete, and importing react-native-url-polyfill/auto swaps the global URL and URLSearchParams for versions that follow the web’s URL standard, as soon as that file loads.

What changed in React Native

Through React Native 0.79, most URL properties weren’t implemented, so reading one threw an error such as URL.hostname is not implemented. That’s the error a Supabase app without the polyfill ran into on those versions, because of how supabase-js works: its endpoints are built with new URL("auth/v1", baseUrl), and the saved session is named after the project’s hostname.

From 0.80 on, including the 0.83 that Draftbit apps use today, those properties return values. They’re still read with pattern matching rather than the URL standard, though. For example, a trailing slash is added to any address without a query or a #, so https://example.com/path becomes https://example.com/path/, and hostname comes back empty for anything other than http and https addresses, such as your app’s own myapp:// links.

Do you still need it?

For a Supabase app, yes. Supabase’s current Expo quickstart has you install it and import it before creating the client, and we’d stick with the setup in Supabase’s own guide, since it’s the low-risk choice. According to its README, the polyfill adds about 25 kB to the JavaScript bundle, and on the web the auto import does nothing.

Without Supabase it’s optional, so add it when a library or your own code needs URL to behave the way it does in a browser.

How to set it up

1. Install it:

   npx expo install react-native-url-polyfill

2. Import it first, before anything creates a URL. In a Supabase app, that’s the top of the client file:

   import "react-native-url-polyfill/auto";
   import { createClient } from "@supabase/supabase-js";
   
   export const supabase = createClient(
     process.env.EXPO_PUBLIC_SUPABASE_URL!,
     process.env.EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
   );

The quickstart’s version of this file also passes auth options for saving the session, which you’ll find in the Supabase link below.

How you know it works

The polyfill sets a global you can log once the app starts:

console.log((globalThis as any).REACT_NATIVE_URL_POLYFILL);
// "react-native-url-polyfill@4.0.0", or whichever version you installed

If it logs undefined, the import hasn’t run.

If you still see URL errors

Check that no other file creates a Supabase client or a URL before the import runs, for example a second client file or a provider loaded earlier. Then restart the bundler with npx expo start --clear, so you’re not running an old bundle. The polyfill doesn’t support hostnames with non-ASCII characters, since that support was left out to keep its size down. If the error is a failed sign-in rather than a URL error, see why a Supabase login isn’t working.