
Type-safe, coroutine-first, modular client for Supabase with Result monad, value-class IDs, PostgREST filter DSL, OAuth+MFA, session auto-refresh, realtime, storage, and edge functions.
Kotlin Multiplatform SDK for Supabase — type-safe, coroutine-first, modular client for every platform Kotlin runs on.
SupabaseResult<T> with map, flatMap, recover — no exceptions leak to callersUserId, BucketId, SessionId, ChannelId prevent mixups at compile timeeq, neq, gt, like, ilike, in, is, textSearch, contains, and moreSessionState observation via StateFlow
Add the dependencies you need to your build.gradle.kts:
// Version catalog (gradle/libs.versions.toml)
[versions]
supabase-kmp = "0.2.0"
[libraries]
supabase-core = { module = "io.github.androidpoet:supabase-core", version.ref = "supabase-kmp" }
supabase-client = { module = "io.github.androidpoet:supabase-client", version.ref = "supabase-kmp" }
supabase-auth = { module = "io.github.androidpoet:supabase-auth", version.ref = "supabase-kmp" }
supabase-database = { module = "io.github.androidpoet:supabase-database", version.ref = "supabase-kmp" }
supabase-storage = { module = "io.github.androidpoet:supabase-storage", version.ref = "supabase-kmp" }
supabase-realtime = { module = "io.github.androidpoet:supabase-realtime", version.ref = "supabase-kmp" }
supabase-functions = { module = "io.github.androidpoet:supabase-functions", version.ref = "supabase-kmp" }// build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.supabase.client) // includes supabase-core
implementation(libs.supabase.auth) // optional
implementation(libs.supabase.database) // optional
implementation(libs.supabase.storage) // optional
implementation(libs.supabase.realtime) // optional
implementation(libs.supabase.functions) // optional
}
}
}// Direct instantiation
val client = Supabase.create(
projectUrl = "https://your-project.supabase.co",
apiKey = "your-anon-key",
) {
logging = true
}
// Or with Koin DI
startKoin {
modules(
supabaseModule(
projectUrl = "https://your-project.supabase.co",
apiKey = "your-anon-key",
config = SupabaseConfig(),
),
authModule(),
databaseModule,
storageModule,
realtimeModule(),
functionsModule,
)
}
val auth: AuthClient by inject()
val database: DatabaseClient by inject()@Serializable
data class Todo(val id: String, val title: String, val done: Boolean)
// Select with filters
val todos: SupabaseResult<List<Todo>> = database.selectTyped<Todo>(
table = "todos",
) {
eq("done", "false")
gt("priority", "3")
order("created_at", ascending = false)
limit(25)
}
todos.onSuccess { items ->
println("Got ${items.size} todos")
}.onFailure { error ->
println("Error: ${error.message}")
}
// Insert
val result = database.insertTyped(
table = "todos",
value = Todo(id = "1", title = "Ship it", done = false),
)
// Update with filters
database.update(table = "todos", body = """{"done": true}""") {
eq("id", "1")
}
// RPC call
val stats = database.rpc("get_dashboard_stats", params = """{"user_id": "123"}""")val auth: AuthClient by inject()
val sessionManager: SessionManager by inject()
// Email/password sign-up
auth.signUpWithEmail(
email = "user@example.com",
password = "secure-password",
).onSuccess { session ->
sessionManager.saveSession(session)
}
// Email/password sign-in
auth.signInWithEmail(
email = "user@example.com",
password = "secure-password",
).onSuccess { session ->
sessionManager.saveSession(session)
}
// OAuth — get URL for the provider, open in browser
val oauthUrl = auth.getOAuthSignInUrl(
provider = OAuthProvider.GOOGLE,
redirectTo = "myapp://callback",
)
// After OAuth callback, exchange the code
val pkce = auth.generatePkceParams()
auth.exchangeCodeForSession(authCode = "code-from-callback", codeVerifier = pkce.codeVerifier)
// MFA enrollment
val accessToken = sessionManager.accessToken!!
auth.mfaEnroll(factorType = MfaFactorType.TOTP, accessToken = accessToken).onSuccess { factor ->
// Show factor.totp?.qrCode to user, then verify:
auth.mfaVerify(
factorId = factor.id,
challengeId = "challenge-id",
code = "123456",
accessToken = accessToken,
)
}
// Observe session state
sessionManager.sessionState.collect { state ->
when (state) {
is SessionState.Authenticated -> println("User: ${state.session.user.id}")
is SessionState.Expired -> println("Session expired, refreshing...")
SessionState.NotAuthenticated -> println("Signed out")
SessionState.Loading -> println("Loading...")
}
}val storage: StorageClient by inject()
// Upload a file
storage.upload(
bucket = "avatars",
path = "user123/avatar.png",
data = imageBytes,
contentType = "image/png",
).onSuccess { key ->
println("Uploaded: $key")
}
// Get a signed URL
storage.createSignedUrl(
bucket = "avatars",
path = "user123/avatar.png",
expiresIn = 3600,
).onSuccess { url ->
println("Signed URL: $url")
}
// Get public URL (no auth needed)
val publicUrl = storage.getPublicUrl(bucket = "avatars", path = "user123/avatar.png")
// List files
storage.list(bucket = "avatars", prefix = "user123/").onSuccess { files ->
files.forEach { println(it.name) }
}val realtime: RealtimeClient by inject()
// Connect and observe connection state
realtime.connect()
realtime.connectionState.collect { state ->
when (state) {
is ConnectionState.Connected -> println("Connected")
is ConnectionState.Reconnecting -> println("Reconnecting attempt ${state.attempt}...")
is ConnectionState.Failed -> println("Failed: ${state.reason}")
else -> {}
}
}
// Subscribe to table changes
val subscription = realtime.channel("todos")
.onPostgresChange(table = "todos", event = PostgresChangeEvent.INSERT) { record ->
println("New todo: $record")
}
.onPostgresChange(table = "todos", event = PostgresChangeEvent.DELETE) { record ->
println("Deleted: $record")
}
.subscribe()
// Presence
realtime.channel("room:lobby")
.onPresence { state ->
println("Online users: ${state.size}")
}
.subscribe()
// Broadcast
subscription.broadcast(event = "cursor", payload = buildJsonObject {
put("x", 100)
put("y", 200)
})
// Unsubscribe
subscription.unsubscribe()
realtime.disconnect()val functions: FunctionsClient by inject()
// Invoke a function
functions.invoke(
functionName = "hello-world",
body = """{"name": "Kotlin"}""",
).onSuccess { data ->
println("Response: $data")
}
// Typed response
functions.invokeTyped<WelcomeResponse>(
functionName = "hello-world",
body = """{"name": "Kotlin"}""",
).onSuccess { response ->
println("Message: ${response.message}")
}
// Binary body
functions.invokeWithBody(
functionName = "process-image",
body = imageBytes,
contentType = "image/png",
)┌─────────────────────────────────────────────────────────────────────┐
│ Your App │
├──────────┬───────────┬───────────┬───────────┬───────────┬─────────┤
│ supabase │ supabase │ supabase │ supabase │ supabase │supabase │
│ auth │ database │ storage │ realtime │ functions │ client │
│ │ │ │ │ │ │
│ OAuth │ PostgREST │ Buckets │ WebSocket │ Invoke │ HTTP │
│ MFA/PKCE │ Filter DSL│ Upload │ Phoenix │ Typed Req │ Auth │
│ Session │ RPC │ SignedURL │ Presence │ Response │ Koin DI │
│ Manager │ Typed Ext │ Public URL│ Reconnect │ Binary │ Config │
├──────────┴───────────┴───────────┼───────────┤ │ │
│ │ Ktor │ │ │
│ │ Engines │ │ │
├───────────────────────────────────┴───────────┤ │ │
│ supabase-core │ │ │
│ SupabaseResult · Value IDs · Filter DSL │ │ │
│ Error Types · Response Models │ │ │
└────────────────────────────────────────────────┴───────────┴─────────┘
| Module | Artifact | Description |
|---|---|---|
| supabase-core | io.github.androidpoet:supabase-core |
Result monad, error types, value class IDs, filter DSL |
| supabase-client | io.github.androidpoet:supabase-client |
HTTP transport, platform engines, auth state, Koin module |
| supabase-auth | io.github.androidpoet:supabase-auth |
Email, phone, OTP, OAuth (17 providers), MFA, PKCE, session management |
| supabase-database | io.github.androidpoet:supabase-database |
PostgREST CRUD, RPC, typed filter extensions |
| supabase-storage | io.github.androidpoet:supabase-storage |
Bucket CRUD, file upload/download, signed & public URLs |
| supabase-realtime | io.github.androidpoet:supabase-realtime |
WebSocket (Phoenix protocol), auto-reconnect, broadcast, presence |
| supabase-functions | io.github.androidpoet:supabase-functions |
Edge function invocation with typed responses |
| Platform | Target | Ktor Engine |
|---|---|---|
| Android | androidTarget() |
OkHttp |
| JVM | jvm() |
OkHttp |
| iOS |
iosX64() iosArm64() iosSimulatorArm64()
|
Darwin |
| macOS |
macosX64() macosArm64()
|
Darwin |
| tvOS |
tvosX64() tvosArm64() tvosSimulatorArm64()
|
Darwin |
| watchOS |
watchosX64() watchosArm64() watchosSimulatorArm64()
|
Darwin |
| Linux | linuxX64() |
CIO |
| Windows | mingwX64() |
CIO |
| Web | wasmJs() |
Js |
| supabase-kmp | supabase-kt (official) | |
|---|---|---|
| Codebase | ~3K LOC | ~26K LOC |
| Error handling |
SupabaseResult<T> monad |
Thrown exceptions |
| Type safety | Value class IDs | String IDs |
| DI | Koin modules | Manual composition |
| Dependencies | 3 core | 7+ |
| Session mgmt |
SessionManager + StateFlow
|
Built-in (heavier) |
| Reconnection | Exponential backoff | Exponential backoff |
| Targets | 15 | 15+ |
| Layer | Library |
|---|---|
| Language | Kotlin 2.1.10 |
| Networking | Ktor 3.1.1 |
| Serialization | kotlinx.serialization 1.8.0 |
| Coroutines | kotlinx.coroutines 1.10.1 |
| DI | Koin 4.0.2 |
| Publishing | vanniktech maven-publish 0.30.0 |
# Compile all targets
./gradlew compileKotlinJvm
# Run tests
./gradlew jvmTest
# Full build (all platforms)
./gradlew build --no-configuration-cache
# Publish to Maven Central (CI only, auto-release)
./gradlew publishAndReleaseToMavenCentral --no-configuration-cachedocs/
.gitbook.yaml
docs/guides/gitbook-publishing.md
mkdocs.yml
requirements-docs.txt
python -m pip install -r requirements-docs.txt
mkdocs servemkdocs gh-deploy --forceMIT License
Copyright (c) 2026 Ranbir Singh
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Kotlin Multiplatform SDK for Supabase — type-safe, coroutine-first, modular client for every platform Kotlin runs on.
SupabaseResult<T> with map, flatMap, recover — no exceptions leak to callersUserId, BucketId, SessionId, ChannelId prevent mixups at compile timeeq, neq, gt, like, ilike, in, is, textSearch, contains, and moreSessionState observation via StateFlow
Add the dependencies you need to your build.gradle.kts:
// Version catalog (gradle/libs.versions.toml)
[versions]
supabase-kmp = "0.2.0"
[libraries]
supabase-core = { module = "io.github.androidpoet:supabase-core", version.ref = "supabase-kmp" }
supabase-client = { module = "io.github.androidpoet:supabase-client", version.ref = "supabase-kmp" }
supabase-auth = { module = "io.github.androidpoet:supabase-auth", version.ref = "supabase-kmp" }
supabase-database = { module = "io.github.androidpoet:supabase-database", version.ref = "supabase-kmp" }
supabase-storage = { module = "io.github.androidpoet:supabase-storage", version.ref = "supabase-kmp" }
supabase-realtime = { module = "io.github.androidpoet:supabase-realtime", version.ref = "supabase-kmp" }
supabase-functions = { module = "io.github.androidpoet:supabase-functions", version.ref = "supabase-kmp" }// build.gradle.kts
kotlin {
sourceSets {
commonMain.dependencies {
implementation(libs.supabase.client) // includes supabase-core
implementation(libs.supabase.auth) // optional
implementation(libs.supabase.database) // optional
implementation(libs.supabase.storage) // optional
implementation(libs.supabase.realtime) // optional
implementation(libs.supabase.functions) // optional
}
}
}// Direct instantiation
val client = Supabase.create(
projectUrl = "https://your-project.supabase.co",
apiKey = "your-anon-key",
) {
logging = true
}
// Or with Koin DI
startKoin {
modules(
supabaseModule(
projectUrl = "https://your-project.supabase.co",
apiKey = "your-anon-key",
config = SupabaseConfig(),
),
authModule(),
databaseModule,
storageModule,
realtimeModule(),
functionsModule,
)
}
val auth: AuthClient by inject()
val database: DatabaseClient by inject()@Serializable
data class Todo(val id: String, val title: String, val done: Boolean)
// Select with filters
val todos: SupabaseResult<List<Todo>> = database.selectTyped<Todo>(
table = "todos",
) {
eq("done", "false")
gt("priority", "3")
order("created_at", ascending = false)
limit(25)
}
todos.onSuccess { items ->
println("Got ${items.size} todos")
}.onFailure { error ->
println("Error: ${error.message}")
}
// Insert
val result = database.insertTyped(
table = "todos",
value = Todo(id = "1", title = "Ship it", done = false),
)
// Update with filters
database.update(table = "todos", body = """{"done": true}""") {
eq("id", "1")
}
// RPC call
val stats = database.rpc("get_dashboard_stats", params = """{"user_id": "123"}""")val auth: AuthClient by inject()
val sessionManager: SessionManager by inject()
// Email/password sign-up
auth.signUpWithEmail(
email = "user@example.com",
password = "secure-password",
).onSuccess { session ->
sessionManager.saveSession(session)
}
// Email/password sign-in
auth.signInWithEmail(
email = "user@example.com",
password = "secure-password",
).onSuccess { session ->
sessionManager.saveSession(session)
}
// OAuth — get URL for the provider, open in browser
val oauthUrl = auth.getOAuthSignInUrl(
provider = OAuthProvider.GOOGLE,
redirectTo = "myapp://callback",
)
// After OAuth callback, exchange the code
val pkce = auth.generatePkceParams()
auth.exchangeCodeForSession(authCode = "code-from-callback", codeVerifier = pkce.codeVerifier)
// MFA enrollment
val accessToken = sessionManager.accessToken!!
auth.mfaEnroll(factorType = MfaFactorType.TOTP, accessToken = accessToken).onSuccess { factor ->
// Show factor.totp?.qrCode to user, then verify:
auth.mfaVerify(
factorId = factor.id,
challengeId = "challenge-id",
code = "123456",
accessToken = accessToken,
)
}
// Observe session state
sessionManager.sessionState.collect { state ->
when (state) {
is SessionState.Authenticated -> println("User: ${state.session.user.id}")
is SessionState.Expired -> println("Session expired, refreshing...")
SessionState.NotAuthenticated -> println("Signed out")
SessionState.Loading -> println("Loading...")
}
}val storage: StorageClient by inject()
// Upload a file
storage.upload(
bucket = "avatars",
path = "user123/avatar.png",
data = imageBytes,
contentType = "image/png",
).onSuccess { key ->
println("Uploaded: $key")
}
// Get a signed URL
storage.createSignedUrl(
bucket = "avatars",
path = "user123/avatar.png",
expiresIn = 3600,
).onSuccess { url ->
println("Signed URL: $url")
}
// Get public URL (no auth needed)
val publicUrl = storage.getPublicUrl(bucket = "avatars", path = "user123/avatar.png")
// List files
storage.list(bucket = "avatars", prefix = "user123/").onSuccess { files ->
files.forEach { println(it.name) }
}val realtime: RealtimeClient by inject()
// Connect and observe connection state
realtime.connect()
realtime.connectionState.collect { state ->
when (state) {
is ConnectionState.Connected -> println("Connected")
is ConnectionState.Reconnecting -> println("Reconnecting attempt ${state.attempt}...")
is ConnectionState.Failed -> println("Failed: ${state.reason}")
else -> {}
}
}
// Subscribe to table changes
val subscription = realtime.channel("todos")
.onPostgresChange(table = "todos", event = PostgresChangeEvent.INSERT) { record ->
println("New todo: $record")
}
.onPostgresChange(table = "todos", event = PostgresChangeEvent.DELETE) { record ->
println("Deleted: $record")
}
.subscribe()
// Presence
realtime.channel("room:lobby")
.onPresence { state ->
println("Online users: ${state.size}")
}
.subscribe()
// Broadcast
subscription.broadcast(event = "cursor", payload = buildJsonObject {
put("x", 100)
put("y", 200)
})
// Unsubscribe
subscription.unsubscribe()
realtime.disconnect()val functions: FunctionsClient by inject()
// Invoke a function
functions.invoke(
functionName = "hello-world",
body = """{"name": "Kotlin"}""",
).onSuccess { data ->
println("Response: $data")
}
// Typed response
functions.invokeTyped<WelcomeResponse>(
functionName = "hello-world",
body = """{"name": "Kotlin"}""",
).onSuccess { response ->
println("Message: ${response.message}")
}
// Binary body
functions.invokeWithBody(
functionName = "process-image",
body = imageBytes,
contentType = "image/png",
)┌─────────────────────────────────────────────────────────────────────┐
│ Your App │
├──────────┬───────────┬───────────┬───────────┬───────────┬─────────┤
│ supabase │ supabase │ supabase │ supabase │ supabase │supabase │
│ auth │ database │ storage │ realtime │ functions │ client │
│ │ │ │ │ │ │
│ OAuth │ PostgREST │ Buckets │ WebSocket │ Invoke │ HTTP │
│ MFA/PKCE │ Filter DSL│ Upload │ Phoenix │ Typed Req │ Auth │
│ Session │ RPC │ SignedURL │ Presence │ Response │ Koin DI │
│ Manager │ Typed Ext │ Public URL│ Reconnect │ Binary │ Config │
├──────────┴───────────┴───────────┼───────────┤ │ │
│ │ Ktor │ │ │
│ │ Engines │ │ │
├───────────────────────────────────┴───────────┤ │ │
│ supabase-core │ │ │
│ SupabaseResult · Value IDs · Filter DSL │ │ │
│ Error Types · Response Models │ │ │
└────────────────────────────────────────────────┴───────────┴─────────┘
| Module | Artifact | Description |
|---|---|---|
| supabase-core | io.github.androidpoet:supabase-core |
Result monad, error types, value class IDs, filter DSL |
| supabase-client | io.github.androidpoet:supabase-client |
HTTP transport, platform engines, auth state, Koin module |
| supabase-auth | io.github.androidpoet:supabase-auth |
Email, phone, OTP, OAuth (17 providers), MFA, PKCE, session management |
| supabase-database | io.github.androidpoet:supabase-database |
PostgREST CRUD, RPC, typed filter extensions |
| supabase-storage | io.github.androidpoet:supabase-storage |
Bucket CRUD, file upload/download, signed & public URLs |
| supabase-realtime | io.github.androidpoet:supabase-realtime |
WebSocket (Phoenix protocol), auto-reconnect, broadcast, presence |
| supabase-functions | io.github.androidpoet:supabase-functions |
Edge function invocation with typed responses |
| Platform | Target | Ktor Engine |
|---|---|---|
| Android | androidTarget() |
OkHttp |
| JVM | jvm() |
OkHttp |
| iOS |
iosX64() iosArm64() iosSimulatorArm64()
|
Darwin |
| macOS |
macosX64() macosArm64()
|
Darwin |
| tvOS |
tvosX64() tvosArm64() tvosSimulatorArm64()
|
Darwin |
| watchOS |
watchosX64() watchosArm64() watchosSimulatorArm64()
|
Darwin |
| Linux | linuxX64() |
CIO |
| Windows | mingwX64() |
CIO |
| Web | wasmJs() |
Js |
| supabase-kmp | supabase-kt (official) | |
|---|---|---|
| Codebase | ~3K LOC | ~26K LOC |
| Error handling |
SupabaseResult<T> monad |
Thrown exceptions |
| Type safety | Value class IDs | String IDs |
| DI | Koin modules | Manual composition |
| Dependencies | 3 core | 7+ |
| Session mgmt |
SessionManager + StateFlow
|
Built-in (heavier) |
| Reconnection | Exponential backoff | Exponential backoff |
| Targets | 15 | 15+ |
| Layer | Library |
|---|---|
| Language | Kotlin 2.1.10 |
| Networking | Ktor 3.1.1 |
| Serialization | kotlinx.serialization 1.8.0 |
| Coroutines | kotlinx.coroutines 1.10.1 |
| DI | Koin 4.0.2 |
| Publishing | vanniktech maven-publish 0.30.0 |
# Compile all targets
./gradlew compileKotlinJvm
# Run tests
./gradlew jvmTest
# Full build (all platforms)
./gradlew build --no-configuration-cache
# Publish to Maven Central (CI only, auto-release)
./gradlew publishAndReleaseToMavenCentral --no-configuration-cachedocs/
.gitbook.yaml
docs/guides/gitbook-publishing.md
mkdocs.yml
requirements-docs.txt
python -m pip install -r requirements-docs.txt
mkdocs servemkdocs gh-deploy --forceMIT License
Copyright (c) 2026 Ranbir Singh
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.