AI & Agent Dev Bug Sandbox Back to Radar

Missing React Native CLI Setup Documentation With AsyncStorage Configuration

Supabase documentation lacks a dedicated guide for React Native CLI projects. The default Supabase JS client uses browser localStorage for auth session persistence, which is unavailable on React Native. This causes runtime errors and prevents authentication state persistence unless developers manually configure AsyncStorage.

mediumConfidence 87%React Native

Origin Analysis

The Supabase JS client defaults to browser localStorage for auth storage. React Native does not provide localStorage; it requires AsyncStorage from @react-native-async-storage/async-storage. The official documentation only covers Expo, omitting the necessary AsyncStorage adapter and URL polyfill configuration for React Native CLI.

1. Create a React Native project using the React Native CLI. 2. Install @supabase/supabase-js. 3. Follow the web or Expo documentation to initialize the Supabase client without specifying an auth storage adapter. 4. Attempt to sign in or persist the session. 5. Observe errors such as 'localStorage is not defined' or session not persisting after app restart.

Fixing Code Block

// Install dependencies:
// npm install @supabase/supabase-js @react-native-async-storage/async-storage react-native-url-polyfill

import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState } from 'react-native';
import { createClient } from '@supabase/supabase-js';
import 'react-native-url-polyfill/auto';

const supabaseUrl = 'YOUR_SUPABASE_URL';
const supabaseAnonKey = 'YOUR_SUPABASE_ANON_KEY';

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    storage: AsyncStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});

AppState.addEventListener('change', (state) => {
  if (state === 'active') {
    supabase.auth.startAutoRefresh();
  } else {
    supabase.auth.stopAutoRefresh();
  }
});

Passing AsyncStorage as the auth.storage option replaces the default browser localStorage. The URL polyfill ensures the Supabase client can parse URLs on React Native. AppState listener starts auto-refresh when the app is active and stops it when backgrounded, preserving token refresh cycles and session persistence.

Edge Case Audit

Using AsyncStorage directly works but may not support non-string values; ensure all stored values are strings. AsyncStorage must be manually linked for React Native versions < 0.60. If upgrading from a previous setup without explicit AsyncStorage, stale tokens may exist in localStorage mocks; clear storage after migration. Do not create multiple Supabase clients with different storage adapters in the same app. Test on both Android and iOS. Rollback: remove the custom auth.storage and restore previous client initialization if unexpected behavior occurs, but note that session persistence will break on React Native without an adapter.