API Reference

.github/workflows/docs-deploy.yml

@@ -0,0 +1,52 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [ 'main' ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate Gradle Wrapper
+        uses: gradle/wrapper-validation-action@v1
+      - uses: actions/cache@v3
+        with:
+          path: ~/.konan
+          key: ${{ runner.os }}-${{ hashFiles('**/.lock') }}
+      - name: Set up JDK 17
+        uses: actions/setup-java@v3
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+      - name: Build Docs
+        run: |
+          ./gradlew \
+           -PGITHUB_PUBLISH_TOKEN=${{ secrets.GITHUB_TOKEN }} \
+          dokkaGenerate
+        shell: bash
+      - name: Upload static files as artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/dokka/html
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

build.gradle.kts

@@ -1,3 +1,9 @@
+import com.sun.net.httpserver.HttpExchange
+import com.sun.net.httpserver.HttpServer
+import java.net.InetSocketAddress
+import java.net.URLDecoder
+import java.nio.file.Files
+
 plugins {
     alias(libs.plugins.jetbrainsCompose) apply false
     alias(libs.plugins.compose.compiler) apply false
@@ -16,6 +22,8 @@ plugins {
     alias(libs.plugins.kotlinter) apply false
     alias(libs.plugins.keeper) apply false
     alias(libs.plugins.kotlin.atomicfu) apply false
+    id("org.jetbrains.dokka") version libs.versions.dokkaBase
+    id("dokka-convention")
 }
 
 allprojects {
@@ -54,6 +62,58 @@ subprojects {
     version = LIBRARY_VERSION
 }
 
-tasks.register<Delete>("clean") {
+tasks.getByName<Delete>("clean") {
     delete(rootProject.layout.buildDirectory)
 }
+
+// Merges individual module docs into a single HTML output
+dependencies {
+    dokka(project(":core:"))
+    dokka(project(":connectors:supabase"))
+    dokka(project(":compose:"))
+}
+
+dokka {
+    moduleName.set("PowerSync Kotlin")
+}
+
+// Serve the generated Dokka documentation using a simple HTTP server
+// File changes are not watched here
+tasks.register("serveDokka") {
+    group = "dokka"
+    dependsOn("dokkaGenerate")
+    doLast {
+        val server = HttpServer.create(InetSocketAddress(0), 0)
+        val root = file("build/dokka/html")
+
+        val handler =
+            com.sun.net.httpserver.HttpHandler { exchange: HttpExchange ->
+                val rawPath = exchange.requestURI.path
+                val cleanPath = URLDecoder.decode(rawPath.removePrefix("/"), "UTF-8")
+                val requestedFile = File(root, cleanPath)
+
+                val file =
+                    when {
+                        requestedFile.exists() && !requestedFile.isDirectory -> requestedFile
+                        else -> File(root, "index.html") // fallback
+                    }
+
+                val contentType =
+                    Files.probeContentType(file.toPath()) ?: "application/octet-stream"
+                val bytes = file.readBytes()
+                exchange.responseHeaders.add("Content-Type", contentType)
+                exchange.sendResponseHeaders(200, bytes.size.toLong())
+                exchange.responseBody.use { it.write(bytes) }
+            }
+
+        server.createContext("/", handler)
+        server.executor = null
+        server.start()
+
+        println("📘 Serving Dokka docs at http://localhost:${server.address.port}/")
+        println("Press Ctrl+C to stop.")
+
+        // Keep the task alive
+        Thread.currentThread().join()
+    }
+}

compose/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
     alias(libs.plugins.compose.compiler)
     alias(libs.plugins.kotlinter)
     id("com.powersync.plugins.sonatype")
+    id("dokka-convention")
 }
 
 kotlin {
@@ -45,3 +46,7 @@ android {
 }
 
 setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Compose")
+}

connectors/supabase/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
     alias(libs.plugins.androidLibrary)
     alias(libs.plugins.kotlinter)
     id("com.powersync.plugins.sonatype")
+    id("dokka-convention")
 }
 
 kotlin {
@@ -51,3 +52,7 @@ android {
 }
 
 setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Supabase Connector")
+}

core/build.gradle.kts

@@ -19,6 +19,7 @@ plugins {
     id("com.powersync.plugins.sharedbuild")
     alias(libs.plugins.mokkery)
     alias(libs.plugins.kotlin.atomicfu)
+    id("dokka-convention")
 }
 
 val binariesFolder = project.layout.buildDirectory.dir("binaries/desktop")
@@ -295,3 +296,7 @@ tasks.withType<KotlinTest> {
     }
 }
 setupGithubRepository()
+
+dokka {
+    moduleName.set("PowerSync Core")
+}

core/src/androidMain/kotlin/BuildConfig.kt

@@ -1,5 +1,5 @@
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
-public actual object BuildConfig {
-    public actual val isDebug: Boolean
+internal actual object BuildConfig {
+    actual val isDebug: Boolean
         get() = com.powersync.BuildConfig.DEBUG
 }

core/src/appleMain/kotlin/BuildConfig.kt

@@ -2,7 +2,7 @@ import kotlin.experimental.ExperimentalNativeApi
 import kotlin.native.Platform
 
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
-public actual object BuildConfig {
+internal actual object BuildConfig {
     @OptIn(ExperimentalNativeApi::class)
-    public actual val isDebug: Boolean = Platform.isDebugBinary
+    actual val isDebug: Boolean = Platform.isDebugBinary
 }

core/src/commonMain/kotlin/BuildConfig.kt

@@ -1,4 +1,4 @@
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
-public expect object BuildConfig {
-    public val isDebug: Boolean
+internal expect object BuildConfig {
+    val isDebug: Boolean
 }

core/src/commonMain/kotlin/com/powersync/db/schema/Schema.kt

@@ -2,15 +2,30 @@ package com.powersync.db.schema
 
 import kotlinx.serialization.Serializable
 
+/**
+ * The schema used by the database.
+ *
+ * The implementation uses the schema as a "VIEW" on top of JSON data.
+ * No migrations are required on the client.
+ */
 public data class Schema(
     val tables: List<Table>,
 ) {
     init {
         validate()
     }
 
+    /**
+     * Secondary constructor to create a schema with a variable number of tables.
+     */
     public constructor(vararg tables: Table) : this(tables.asList())
 
+    /**
+     * Validates the schema by ensuring there are no duplicate table names
+     * and that each table is valid.
+     *
+     * @throws AssertionError if duplicate table names are found.
+     */
     public fun validate() {
         val tableNames = mutableSetOf<String>()
         tables.forEach { table ->

core/src/jvmMain/kotlin/BuildConfig.kt

@@ -1,12 +1,12 @@
 @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING")
-public actual object BuildConfig {
+internal actual object BuildConfig {
     /*
       To debug on the JVM, you can:
       - Set the com.powersync.debug property with System.setProperty("com.powersync.debug", true) BEFORE calling any powersync API.
       - Start your java program with the -Dcom.powersync.debug=true command line argument.
       - Set the POWERSYNC_JVM_DEBUG environment variable to "true" before starting your program.
      */
-    public actual val isDebug: Boolean =
+    actual val isDebug: Boolean =
         System.getProperty("com.powersync.debug") == "true" ||
             System.getenv("POWERSYNC_JVM_DEBUG") == "true"
 }

docs/assets/doc-styles.css

@@ -0,0 +1,34 @@
+:root {
+    --dokka-logo-image-url: url('../images/powersync-logo.png');
+}
+
+.footer-container {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 8px;
+    margin-top: auto;
+    box-sizing: border-box;
+    background-color: var(--footer-background);
+    color: var(--footer-font-color);
+}
+
+.footer-title {
+    margin-bottom: 8px;
+}
+
+.footer-column {
+    flex: 1 1 0; 
+    align-items: center;
+    text-align: center;
+    min-width: 300px; 
+    padding: 8px;
+}
+
+.footer-icon-row {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    gap: 8px;
+    flex-wrap: wrap;
+  }

docs/assets/dokka-templates/includes/footer.ftl

@@ -0,0 +1,48 @@
+<#macro display>
+<@template_cmd name="pathToRoot">
+<div style="margin-top:auto">
+<div class="footer-container">
+  <div class="footer-column">
+    <strong class="footer-title">Community</strong>
+    <div class="footer-icon-row">
+      <a href="https://discord.gg/powersync" target="_blank">
+        <img src="./${pathToRoot}images/discord.svg" loading="lazy" alt="Discord" height="24">
+      </a>
+      <a href="https://twitter.com/powersync_" target="_blank">
+        <img src="./${pathToRoot}images/x.svg" loading="lazy" alt="Twitter" height="20">
+      </a>
+      <a href="https://www.youtube.com/@powersync_" target="_blank">
+        <img src="./${pathToRoot}images/youtube.svg" loading="lazy" alt="YouTube" width="32" height="28">
+      </a>
+      <a href="https://www.linkedin.com/showcase/journeyapps-powersync/" target="_blank">
+        <img src="./${pathToRoot}images/linkedin.svg" loading="lazy" alt="LinkedIn" height="24">
+      </a>
+    </div>
+  </div>
+
+  <div class="footer-column">
+    <strong class="footer-title">More</strong>
+    <div class="footer-icon-row">
+      <a href="https://github.com/powersync-ja" target="_blank">
+        <img src="./${pathToRoot}images/github.svg" loading="lazy" alt="GitHub" height="24">
+      </a>
+      <a href="https://www.powersync.com/" target="_blank">
+        <img src="./${pathToRoot}images/web.svg" loading="lazy" alt="Website" height="30">
+      </a>
+    </div>
+  </div>
+</div>
+
+<div class="footer-container">
+    <span>© 2025 Journey Mobile, Inc.</span>
+    <span class="pull-right">
+        <span>Generated by </span>
+            <a class="footer--link footer--link_external" href="https://github.com/Kotlin/dokka">
+                <span>dokka</span>
+            </a>
+    </span>
+</div>
+
+</div>
+</@template_cmd>
+</#macro>