Skip to main content

Get started

Latest stable version Latest dev version Kotlin 2.4.0+ IntelliJ IDEA 2026.2+

library-api-watchdog is a set of compiler checks for library authors. It finds public API declarations that are hard to evolve: shapes that can't change later without a breaking change for the library's users.

Every check is on by default and reports a compilation error, except Undocumented public API, which reports a warning. Configuration changes the severity of a check or turns it off. Exemptions and internal API exempts a declaration.

What it looks like​

A public data class with a mutable collection property and without KDoc gets three diagnostics at once:

tip

Diagnostics in code examples are interactive. Hover over an underlined range to read the diagnostic and follow its link to the full documentation.

public data class Config(
public val tags: MutableList<String>
)

The fixed version has KDoc, a read-only collection, and a plain class. Poko generates its equals, hashCode, and toString:

/** Immutable request configuration. */
public class Config(
/** Labels attached to this configuration. */
public val tags: List<String>,
)

Quick setup​

Apply the Kotlin and Watchdog plugins and turn on explicit API mode:

build.gradle.kts
plugins {
kotlin("multiplatform") version "2.4.0"
kotlin("library.api-watchdog") version "0.2.0"
}
kotlin {
explicitApi() // Required to enable checks
}

The plugin also works for Kotlin/JVM and Android projects.

See Configuration for more details about the setup and options.

A published library gets many diagnostics on the first run. The exemptExistingApi task exempts every error in one run. See Adding the plugin to existing libraries for more details.

All checks​

API surface checks​

Java interop checks​

The Java interop checks run only in JVM compilations.

DSL marker checks​

Meaningful exemptions​

Next steps​