@capgo/capacitor-supabase

Use the native Supabase SDKs from your Capacitor app for auth and database calls, and get JWTs for your web layer.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-supabase in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-supabase to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Auth methods: email and password, sign up, anonymous, OAuth providers and OTP with verifyOtp().
• Sessions: getSession(), refreshSession(), setSession(), getUser() and signOut(), with the authStateChange event.
• JWT access: sessions include the access token for your own API calls.
• Database: select(), insert(), update() and delete() on your tables.
• Native SDKs: supabase-swift on iOS and supabase-kt on Android.
• Platforms: iOS and Android. On web, use @supabase/supabase-js directly.

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

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-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:

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: '[email protected]',
  password: 'password123'
});

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

Sign Up

const { session, user } = await CapacitorSupabase.signUp({
  email: '[email protected]',
  password: 'password123',
  data: { name: 'John Doe' }
});

Sign In Anonymously

const { session, user } = await CapacitorSupabase.signInAnonymously();
console.log('Anonymous user ID:', user?.id);

OAuth Sign In

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

OTP Sign In

// Send OTP
await CapacitorSupabase.signInWithOtp({
  email: '[email protected]'
});

// Verify OTP
const { session, user } = await CapacitorSupabase.verifyOtp({
  email: '[email protected]',
  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: '[email protected]',
  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(...)
• signInWithPassword(...)
• signUp(...)
• signInAnonymously()
• signInWithOAuth(...)
• signInWithOtp(...)
• verifyOtp(...)
• signOut()
• getSession()
• refreshSession()
• getUser()
• setSession(...)
• addListener('authStateChange', ...)
• removeAllListeners()
• select(...)
• insert(...)
• update(...)
• delete(...)
• getPluginVersion()
• Interfaces
• Type Aliases

Capacitor Supabase Plugin for native Supabase SDK integration.

This plugin provides native iOS and Android Supabase SDK functionality with the ability to retrieve JWT tokens for use in JavaScript/web layers.

initialize(...)

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

Initialize the Supabase client with your project credentials. Must be called before any other methods.

Since: 0.0.1

signInWithPassword(...)

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

Sign in with email and password.

Returns: Promise<AuthResult>

Since: 0.0.1

signUp(...)

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

Sign up a new user with email and password.

Returns: Promise<AuthResult>

Since: 0.0.1

signInAnonymously()

signInAnonymously() => Promise<AuthResult>

Sign in anonymously. Creates a temporary guest session without requiring credentials.

Returns: Promise<AuthResult>

Since: 0.0.1

signInWithOAuth(...)

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

Sign in with an OAuth provider. Opens the provider's authentication page.

Since: 0.0.1

signInWithOtp(...)

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

Sign in with OTP (One-Time Password) sent via email or SMS.

Since: 0.0.1

verifyOtp(...)

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

Verify an OTP token.

Returns: Promise<AuthResult>

Since: 0.0.1

signOut()

signOut() => Promise<void>

Sign out the current user.

Since: 0.0.1

getSession()

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

Get the current session if one exists. Returns the session with JWT access token.

Returns: Promise<{ session: Session | null; }>

Since: 0.0.1

refreshSession()

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

Refresh the current session and get new tokens.

Returns: Promise<{ session: Session | null; }>

Since: 0.0.1

getUser()

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

Get the currently authenticated user.

Returns: Promise<{ user: User | null; }>

Since: 0.0.1

setSession(...)

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

Set the session manually with access and refresh tokens. Useful for restoring a session or integrating with external auth.

Returns: Promise<{ session: Session | null; }>

Since: 0.0.1

addListener('authStateChange', ...)

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

Listen to authentication state changes.

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for auth state changes.

Since: 0.0.1

select(...)

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

Execute a SELECT query on a table.

Returns: Promise<QueryResult<T[]>>

Since: 0.0.1

insert(...)

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

Insert data into a table.

Returns: Promise<QueryResult<T>>

Since: 0.0.1

update(...)

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

Update data in a table.

Returns: Promise<QueryResult<T>>

Since: 0.0.1

delete(...)

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

Delete data from a table.

Returns: Promise<QueryResult<T>>

Since: 0.0.1

getPluginVersion()

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

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 0.0.1

Interfaces

SupabaseConfig

Configuration options for initializing the Supabase client.

AuthResult

Result of authentication operations that return a session.

Session

Session object containing authentication tokens.

User

User object returned from authentication operations.

SignInWithPasswordOptions

Options for email/password sign-in.

SignUpOptions

Options for email/password sign-up.

SignInWithOAuthOptions

Options for OAuth sign-in.

SignInWithOtpOptions

Options for OTP sign-in.

VerifyOtpOptions

Options for verifying OTP.

SetSessionOptions

Options for setting a session manually.

PluginListenerHandle

AuthStateChange

Auth state change callback data.

QueryResult

Result of database queries.

SelectOptions

Options for database select queries.

InsertOptions

Options for database insert queries.

UpdateOptions

Options for database update queries.

DeleteOptions

Options for database delete queries.

Type Aliases

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

OAuthProvider

Supported OAuth providers.

'apple' | 'azure' | 'bitbucket' | 'discord' | 'facebook' | 'figma' | 'github' | 'gitlab' | 'google' | 'kakao' | 'keycloak' | 'linkedin' | 'linkedin_oidc' | 'notion' | 'slack' | 'slack_oidc' | 'spotify' | 'twitch' | 'twitter' | 'workos' | 'zoom'

AuthChangeEvent

Auth state change event types.

'INITIAL_SESSION' | 'SIGNED_IN' | 'SIGNED_OUT' | 'TOKEN_REFRESHED' | 'USER_UPDATED' | 'PASSWORD_RECOVERY'

License

MPL-2.0