Getting Started

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-supabase` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

bun add @capgo/capacitor-supabase
bunx cap sync

Quick start

import { CapacitorSupabase } from '@capgo/capacitor-supabase';

await CapacitorSupabase.initialize({
  supabaseUrl: 'https://xyzcompany.supabase.co',
  supabaseKey: 'your-anon-key'
});

Example: signInWithPassword

import { CapacitorSupabase } from '@capgo/capacitor-supabase';

const { session, user } = await CapacitorSupabase.signInWithPassword({
  email: 'user@example.com',
  password: 'password123'
});
console.log('JWT:', session?.accessToken);

Example: signUp

import { CapacitorSupabase } from '@capgo/capacitor-supabase';

const { session, user } = await CapacitorSupabase.signUp({
  email: 'newuser@example.com',
  password: 'password123',
  data: { name: 'John Doe' }
});

Common pitfalls

• Listeners: remove handles when screens unmount.
• Initialize once: run setup during app bootstrap.
• Source of truth: trust src/definitions.ts in the GitHub repo.

Android Minimum SDK

The Android implementation requires Android 8.0 or newer. Set minSdkVersion = 26 in android/variables.gradle.

Initialize The Client

import { CapacitorSupabase } from '@capgo/capacitor-supabase';

await CapacitorSupabase.initialize({
  supabaseUrl: 'https://your-project.supabase.co',
  supabaseKey: 'your-anon-key',
});

Sign In And Access The JWT

const { session, user } = await CapacitorSupabase.signInWithPassword({
  email: 'user@example.com',
  password: 'password123',
});

console.log('User', user?.id);
console.log('JWT available', Boolean(session?.accessToken));

Listen For Auth Changes

const listener = await CapacitorSupabase.addListener('authStateChange', ({ event, session }) => {
  console.log('Auth event', event);
  console.log('Current JWT available', Boolean(session?.accessToken));
});

await listener.remove();

Pair Native Auth With supabase-js

import { createClient } from '@supabase/supabase-js';

const { session } = await CapacitorSupabase.getSession();

const supabase = createClient('https://your-project.supabase.co', 'your-anon-key', {
  global: {
    headers: {
      Authorization: `Bearer ${session?.accessToken}`,
    },
  },
});

const { data } = await supabase.from('table').select('*');
console.log(data);

Native Database Helpers

const { data, error } = await CapacitorSupabase.select({
  table: 'users',
  columns: 'id, name, email',
  filter: { active: true },
  limit: 10,
  orderBy: 'created_at',
  ascending: false,
});

console.log(data, error);

Recommended Usage

• Use this plugin for authentication and session management.
• Keep Realtime, Storage, Edge Functions, and advanced querying in @supabase/supabase-js.
• Pass the native JWT into the JavaScript client whenever you need the rest of the Supabase surface area.

Keep going from Getting Started

If you are using Getting Started to plan native plugin work, connect it with Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives, and Capgo Native Builds for the product workflow in Capgo Native Builds.