This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Add a Postgres database and user authentication to your React Native app with Supabase.

Supabase is a Backend-as-a-Service (BaaS) app development platform built on Postgres. It generates a REST API from your database and uses row level security to protect the data, so your React Native app can query that API directly, with no server in between.

The EAS CLI integration automates the standard setup: authorizing your Supabase account, creating or linking a project, installing the SDK, and writing your environment variables. You can also set it up manually and use the rest of this guide unchanged.

What you'll learn

• Install and configure Supabase in your React Native app
• Add authentication with the client you create in Step 2
• Set up environments for local development, Production, and Preview
• Manage the integration and troubleshoot common problems

Install and configure Supabase

import 'expo-sqlite/localStorage/install';
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL!;
const supabasePublishableKey = process.env.EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY!;

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

create table public.todos (
  id bigint generated always as identity primary key,
  title text not null
);
alter table public.todos enable row level security;
create policy "Anyone can read todos" on public.todos for select using (true);
grant select on public.todos to anon, authenticated;
insert into public.todos (title) values ('Hello from Supabase');

import { useEffect, useState } from 'react';
import { Text, View } from 'react-native';
import { supabase } from '@/lib/supabase';

export default function Index() {
  const [titles, setTitles] = useState<string[]>([]);

  useEffect(() => {
    supabase
      .from('todos')
      .select()
      .then(({ data, error }) => {
        if (error) {
          setTitles([error.message]);
          return;
        }
        setTitles(data.map(todo => todo.title));
      });
  }, []);

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      {titles.map(title => (
        <Text key={title}>{title}</Text>
      ))}
    </View>
  );
}

For the concepts behind these steps, see the Supabase database overview:

Add authentication

The client from Step 2 already stores sessions, so email and password sign-in needs no extra configuration. New Supabase projects confirm email addresses by default. Your first signUp returns data.user with data.session set to null until the address is confirmed or you turn off Confirm email in your project's email provider settings.

autoRefreshToken runs its refresh loop continuously on Android and iOS, so Supabase's startAutoRefresh reference recommends tying the loop to app state. Add this to your client file:

import { AppState } from 'react-native';

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

OAuth providers and magic links need a deep link back into your app, covered in Supabase's mobile deep linking guide.

Set up environments

connect stores the values as EAS environment variables, so each build or update reads them from the environment it runs in.

A Supabase project holds one environment's data, so separate environments mean separate projects. Check your Supabase plan limits before creating a second project.

Development runs locally with the Supabase CLI. Start Docker, then run:

Replace the hosted values in .env.local with the API URL and publishable key that supabase status prints. Variables you export in your shell take precedence over .env.local, so edit the file instead of exporting. The local database starts empty, so run your table SQL against it too. Re-running connect writes the hosted values back.

The local URL points at your computer. A physical device or an Android Emulator can't reach it, so use your computer's LAN address there instead of 127.0.0.1.

Production uses the project that connect set up.

Preview has no project of its own by default. To give Preview, or any other EAS environment, its own hosted project, re-run connect with --environment. This creates a second project, which counts toward your plan's active-project limit:

The new project's URL and key go to the named environments only, and your other environments keep pointing at the first project. If the target environments already hold EXPO_PUBLIC_SUPABASE_* values, the command asks to confirm before replacing them. Unlike connect without --environment, this doesn't install the SDK or touch .env.local. You can't combine --environment with --link, --reauth, or --organization.

To point an EAS environment at a Supabase project you already have, set the two variables yourself with eas env:set rather than using --environment. Replace the shared variable with two first, as shown above, so your other environments keep their current project.

Manage the integration

Two commands manage the integration afterward:

dashboard opens your linked Supabase project. disconnect removes the Expo-side link only. Your Supabase project, its data, and your environment variables all stay unchanged.

After you disconnect, connect no longer sees a linked project, so it creates a new one. To point the app back at the same project, run connect --link with its reference ID.

Manual setup

connect is a shortcut for the standard Supabase setup. To do it manually:

1. Create a project at database.new.

2. Copy the Project URL from API Settings and the Publishable key from API Keys.

3. Install the SDK:

   Terminalnpmyarnpnpmbun

   Copy

   - npx expo install @supabase/supabase-js expo-sqlite

4. Add the expo-sqlite config plugin to your app config.

5. Set EXPO_PUBLIC_SUPABASE_URL and EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY in .env.local, then create the client file from Step 2.

Troubleshooting

Further reading