KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

supabase-kmp

★ 47 Open GitHub ↗

A Kotlin Multiplatform (KMP) SDK for Supabase, enabling seamless integration across Android, iOS, and other platforms.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Supabase KMP

Kotlin Multiplatform SDK for [Supabase](https://supabase.com) — type-safe, coroutine-first, modular client for every platform Kotlin runs on.

### 📖 [Read the docs → androidpoet.github.io/supabase-kmp](https://androidpoet.github.io/supabase-kmp/)

Full guides for [Authentication](https://androidpoet.github.io/supabase-kmp/auth), [Database](https://androidpoet.github.io/supabase-kmp/database), [Storage](https://androidpoet.github.io/supabase-kmp/storage), [Realtime](https://androidpoet.github.io/supabase-kmp/realtime) and [Edge Functions](https://androidpoet.github.io/supabase-kmp/functions) live on the docs site. This README is the quick start.

## Features

- **Type-safe Result monad** — `SupabaseResult<T>` with `map`, `flatMap`, `recover` — no exceptions leak to callers
- **Value class IDs** — `UserId`, `BucketId`, `SessionId`, `ChannelId` prevent mixups at compile time
- **Typed filter DSL** — `Column<T>` tokens with infix operators (`eq`, `neq`, `greater`, `like`, `ilike`, `inList`, `isNull`, `textSearch`, `contains`, …); the compiler rejects type mismatches
- **OAuth (17 providers) + MFA** — TOTP and phone-based multi-factor auth with CSPRNG-backed PKCE
- **Native passkeys** — cross-platform WebAuthn ceremony (Android, iOS, macOS, JVM, Wasm) behind a pluggable authenticator, or bring your own
- **Session management** — Single-flight auto-refresh, pluggable persistence (`SessionStorage`), `SessionState` via `StateFlow`
- **Realtime WebSocket** — Phoenix protocol with auto-reconnection, exponential backoff, presence, offline send buffering, binary broadcast (raw `ByteArray`)
- **Secure by default** — Credential headers redacted from logs, smart retries (`429`/`5xx` + `Retry-After`)
- **End-to-end encryption** — Optional `supabase-e2ee`: derive a shared AES-256-GCM key on-device (ECDH → HKDF) so Supabase only ever stores ciphertext. Includes a `KeyDirectory` (publish/fetch public keys), out-of-band `safetyNumber()` verification (MITM protection), and `EncryptedRoom` — a verify-first encrypt-on-send / decrypt-on-receive chat room over `supabase-realtime`
- **16 platform targets** — Android, iOS, macOS, tvOS, watchOS, JVM, Linux, Windows, and WasmJs

## Setup

> **Requirements:** the published Android/JVM artifacts are compiled for **Java 17**
> and ship inline functions, so consuming modules must build with a **`jvmTarget` of
> 17 or higher** (Android `compileOptions`/`kotlinOptions` JVM 17+, or JVM
> `jvmToolchain(17)` or newer — Java 21 is fine). Only a *lower* target fails, with
> *"cannot inline bytecode built with JVM target 17 into bytecode being built with
> JVM target 11"*; matching or higher targets inline cleanly.

Add the modules you need to your version catalog:

```toml
[versions]
supabase-kmp = "1.0.0"

[libraries]
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" }
supabase-sync = { module = "io.github.androidpoet:supabase-sync", version.ref = "supabase-kmp" } # + supabase-sync-core, supabase-sync-sqldelight for offline-first sync

# Optional add-ons — only add the ones you need
supabase-auth-google = { module = "io.github.androidpoet:supabase-auth-google", version.ref = "supabase-kmp" }
supabase-auth-apple = { module = "io.github.androidpoet:supabase-auth-apple", version.ref = "supabase-kmp" }
supabase-auth-passkey = { module = "io.github.androidpoet:supabase-auth-passkey", version.ref = "supabase-kmp" }
supabase-auth-admin = { module = "io.github.androidpoet:supabase-auth-admin", version.ref = "supabase-kmp" }
supabase-e2ee = { module = "io.github.androidpoet:supabase-e2ee", version.ref = "supabase-kmp" }
```

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.supabase.client)
            implementation(libs.supabase.auth)
            implementation(libs.supabase.database)
            implementation(libs.supabase.storage)
            implementation(libs.supabase.realtime)
            implementation(libs.supabase.functions)
        }
    }
}
```

> Only depend on what you use — each module is published independently. Optional add-ons: `supabase-auth-google`, `supabase-auth-apple`, `supabase-auth-passkey` (native sign-in), `supabase-auth-admin` (service-role; server-side only) and `supabase-e2ee` (client-side end-to-end encryption).

## Quick start

Everything starts from a `SupabaseClient`. Create one, then build the feature clients you need from it.

```kotlin
val client = Supabase.create(
    projectUrl = "https://your-project.supabase.co",
    apiKey = "your-anon-key",
) {
    logging = true
}

val auth = createAuthClient(client)
val database = createDatabaseClient(client)
val storage = createStorageClient(client)
val realtime = createRealtimeClient(client)
val functions = createFunctionsClient(client)
```

> Use the **anon** key in client apps — never the service-role key.

## Results, not exceptions

Every fallible call returns a `SupabaseResult<T>` — a sealed `Success`/`Failure` type. There are no exceptions to catch on the happy path; you branch with `onSuccess`/`onFailure` and transform with `map`/`flatMap`/`recover`.

```kotlin
@Serializable
data class Todo(val id: String, val title: String, val done: Boolean)

// Typed column tokens — hand-written here, or emitted by codegen.
object Todos {
 val done = Column<Boolean>("done")
 val createdAt = Column<String>("created_at")
}

database.selectTyped<Todo>(table = "todos") {
 where { Todos.done eq false }
 orderBy(Todos.createdAt, Order.DESC)
 limit(25)
}.onSuccess { todos ->
 println("Got ${todos.size} todos")
}.onFailure { error ->
 println("Error: ${error.message}")
}
```

Errors carry a `category` (`CONFLICT`, `NOT_FOUND`, `UNAUTHORIZED`, `RATE_LIMITED`, `VALIDATION`, `Internal`, `NETWORK`, `UNKNOWN`) so you can branch without parsing codes — plus chainable helpers like `onUnauthorized { }`, `onRateLimited { }` and `onNetworkError { }`. See [Results & Errors](https://androidpoet.github.io/supabase-kmp/results-and-errors) for the full surface.

## Modules

| 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, factory wiring |
| **supabase-auth** | `io.github.androidpoet:supabase-auth` | Email, phone, OTP, OAuth (17 providers), MFA, PKCE, session management, passkeys |
| **supabase-auth-google** | `io.github.androidpoet:supabase-auth-google` | Native Google sign-in (Android Credential Manager) |
| **supabase-auth-apple** | `io.github.androidpoet:supabase-auth-apple` | Native Sign in with Apple (AuthenticationServices) |
| **supabase-auth-passkey** | `io.github.androidpoet:supabase-auth-passkey` | Passkey/WebAuthn ceremony driver — native on Android, iOS, macOS, JVM & Wasm (or bring your own) |
| **supabase-auth-admin** | `io.github.androidpoet:supabase-auth-admin` | Service-role admin APIs (server-side only) |
| **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 |
| **supabase-e2ee** | `io.github.androidpoet:supabase-e2ee` | Optional client-side E2E encryption (ECDH → HKDF → AES-256-GCM) + key directory, safety-number verification & `EncryptedRoom` over realtime |
| **supabase-sync-core** | `io.github.androidpoet:supabase-sync-core` | Offline-first sync engine — pull/merge/push, conflict resolution, keyset cursor (transport-agnostic) |
| **supabase-sync-sqldelight** | `io.github.androidpoet:supabase-sync-sqldelight` | On-device local store over SQLDelight — typed-table SSOT, outbox, cursor, pagination |
| **supabase-sync** | `io.github.androidpoet:supabase-sync` | Supabase remote source — incremental pull/push over PostgREST + live Realtime deltas |

## Targets

Android · JVM · iOS · macOS · tvOS · watchOS · Linux · Windows · WasmJs — 16 targets in total, on OkHttp (Android/JVM), Darwin (Apple), CIO (Linux/Windows) and the JS Ktor engine for the browser (`wasmJs`). The browser target ships only as Kotlin/Wasm via `wasmJs` — there is no separate Kotlin/JS (`js()`) artifact.

## Documentation

- **Docs site:** <https://androidpoet.github.io/supabase-kmp/> (source in [`website/`](website/))
- Release notes: [`CHANGELOG.md`](CHANGELOG.md)
- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
- Security policy: [`SECURITY.md`](SECURITY.md)
- AI Agent Skill (Claude Code / Cursor / Copilot): [`skills/`](skills/)

## Build

```bash
./gradlew compileKotlinJvm                 # compile a single target
./gradlew jvmTest                          # run JVM unit tests
./gradlew build --no-configuration-cache   # full build (all platforms)
```

Quality gates run in CI on every PR — run them locally before pushing:

```bash
./gradlew detekt                    # static analysis (config/detekt/detekt.yml)
./gradlew apiCheck                  # fails on unintended public/binary API changes
./gradlew jvmTest koverHtmlReport   # tests + coverage report
```

If you intentionally change the public API, regenerate the dumps with `./gradlew apiDump` and commit them. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow.

## Contributing

Contributions are welcome! If you've found a bug, have an idea for an improvement, or want to contribute new features, please open an issue or submit a pull request.

## Find this repository useful? :heart:
Support it by joining __[stargazers](https://github.com/androidpoet/supabase-kmp/stargazers)__ for this repository. :star: 
Also, __[follow me](https://github.com/androidpoet)__ on GitHub for my next creations! 🤩

## License

supabase-kmp

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README