@capgo/capacitor-supabase

Native Supabase SDK integration for Capacitor - Auth, Database, and JWT access.

Why Capacitor Supabase?

A native Supabase SDK integration that provides real native authentication with JWT token access for your Capacitor apps:

• Native SDK integration - Full access to Supabase's native iOS and Android SDKs
• JWT token access - Get JWT tokens from native auth for use in JavaScript/web layers
• Complete auth methods - Email/password, OAuth, OTP, magic links, and more
• Session management - Native session handling with automatic token refresh
• Database operations - Native CRUD operations for Supabase tables
• Auth state listeners - Real-time auth state change events
• Hybrid approach - Use native auth with supabase-js for database queries
• Free and open source - No paid services required

Perfect for apps that need secure native authentication while leveraging Supabase's powerful backend services.

Why only Auth and basic DB operations? The Supabase JS SDK already works great in Capacitor for most features (Realtime, Storage, Edge Functions, etc.). Building native bridges for every feature would add complexity without real benefits. This plugin focuses on authentication where native SDKs provide actual value (secure token storage, OAuth flows, biometrics). For everything else, just use @supabase/supabase-js with the JWT from native auth.

Why not bridge everything natively?

• No performance gain - The bridge overhead (JSON serialization/deserialization between JS and native) negates any benefit from skipping HTTP preflight requests. You're just moving the transformation cost from network to CPU.
• Type safety issue - Native SDKs require typed models for every table/query. You'd need to define Swift/Kotlin types for your entire database schema and keep them in sync. With JS, you get dynamic typing that just works.
• Maintenance burden - Every Supabase SDK update would require updating 3 codebases (JS, iOS, Android) instead of just one. The JS SDK is already well-maintained by Supabase.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/supabase/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

npm install @capgo/capacitor-supabase
npx cap sync

iOS Setup

No additional setup required. The plugin uses Swift Package Manager to include the Supabase Swift SDK.

Android Setup

The plugin requires a minimum SDK of 26 (Android 8.0). Make sure your android/variables.gradle has:

minSdkVersion = 26

Usage

Initialize the Client

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

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

Authentication

Sign In with Email/Password

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

// Access the JWT token
console.log('JWT:', session?.accessToken);

Sign Up

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

OAuth Sign In

await CapacitorSupabase.signInWithOAuth({
  provider: 'google',
  redirectTo: 'myapp://callback'
});

OTP Sign In

// Send OTP
await CapacitorSupabase.signInWithOtp({
  email: 'user@example.com'
});

// Verify OTP
const { session, user } = await CapacitorSupabase.verifyOtp({
  email: 'user@example.com',
  token: '123456',
  type: 'email'
});

Sign Out

await CapacitorSupabase.signOut();

Session Management

Get Current Session

const { session } = await CapacitorSupabase.getSession();
if (session) {
  console.log('JWT:', session.accessToken);
  console.log('Refresh Token:', session.refreshToken);
  console.log('Expires At:', session.expiresAt);
}

Refresh Session

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

Get Current User

const { user } = await CapacitorSupabase.getUser();
if (user) {
  console.log('User ID:', user.id);
  console.log('Email:', user.email);
}

Set Session Manually

const { session } = await CapacitorSupabase.setSession({
  accessToken: 'eyJ...',
  refreshToken: 'abc123'
});

Listen to Auth State Changes

const listener = await CapacitorSupabase.addListener(
  'authStateChange',
  ({ event, session }) => {
    console.log('Auth event:', event);
    // Events: INITIAL_SESSION, SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED
    if (session) {
      console.log('JWT:', session.accessToken);
    }
  }
);

// Later, remove the listener
listener.remove();

Using JWT with @supabase/supabase-js

The main use case is to get the JWT from native auth and use it with the JavaScript Supabase client:

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

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

// Sign in natively
await CapacitorSupabase.signInWithPassword({
  email: 'user@example.com',
  password: 'password'
});

// Get session with JWT
const { session } = await CapacitorSupabase.getSession();

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

// Now use supabase-js as normal
const { data } = await supabase.from('table').select('*');

Database Operations (Native)

The plugin also supports native database operations:

Select

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

Insert

const { data, error } = await CapacitorSupabase.insert({
  table: 'posts',
  values: { title: 'Hello', content: 'World' }
});

Update

const { data, error } = await CapacitorSupabase.update({
  table: 'posts',
  values: { title: 'Updated Title' },
  filter: { id: 1 }
});

Delete

const { data, error } = await CapacitorSupabase.delete({
  table: 'posts',
  filter: { id: 1 }
});

API

initialize(options: SupabaseConfig) => Promise<void>

signInWithPassword(options: SignInWithPasswordOptions) => Promise<AuthResult>

signUp(options: SignUpOptions) => Promise<AuthResult>

signInWithOAuth(options: SignInWithOAuthOptions) => Promise<void>

signInWithOtp(options: SignInWithOtpOptions) => Promise<void>

verifyOtp(options: VerifyOtpOptions) => Promise<AuthResult>

signOut() => Promise<void>

getSession() => Promise<{ session: Session | null; }>

refreshSession() => Promise<{ session: Session | null; }>

getUser() => Promise<{ user: User | null; }>

setSession(options: SetSessionOptions) => Promise<{ session: Session | null; }>

addListener(eventName: 'authStateChange', listenerFunc: (data: AuthStateChange) => void) => Promise<PluginListenerHandle>

removeAllListeners() => Promise<void>

select<T = unknown>(options: SelectOptions) => Promise<QueryResult<T[]>>

insert<T = unknown>(options: InsertOptions) => Promise<QueryResult<T>>

update<T = unknown>(options: UpdateOptions) => Promise<QueryResult<T>>

delete<T = unknown>(options: DeleteOptions) => Promise<QueryResult<T>>

getPluginVersion() => Promise<{ version: string; }>

License

MPL-2.0