Ktorfit: generating Kotlin Multiplatform HTTP clients from annotated interfaces

Annotation-defined HTTP clients generated at compile time by KSP

Ktorfit generates HTTP client code for Kotlin Multiplatform projects from annotated Kotlin interfaces, processing those annotations at compile time through Kotlin Symbol Processing (KSP) and connecting the generated output to Ktor clients for the actual HTTP transport. The concept is taken from Retrofit, the HTTP client library for Java: a developer writes an interface with annotations that mark each method as a specific HTTP endpoint, and the tool generates the implementation so no hand-written request handling is needed.

For multiplatform projects, Retrofit is limited to Android and JVM because it is a Java library. Ktorfit addresses that gap by running on KSP, which operates across Kotlin compilation targets including Android, iOS, JVM, JavaScript and Linux. An annotated interface can be shared across those targets in a common module, and the generated Ktor client code at each target is backed by the Ktor engine for that platform.

The repository is maintained by Jens Klingenberg under the Foso GitHub organization. Version 2.7.5 was published on 2026-06-07, and the repository was last pushed on 2026-09-28.

The repository includes 2 example projects: example/AndroidOnlyExample/ for Android-specific setups and example/MultiplatformExample/ for shared-code builds, which show expected project structure alongside the library.

Six packages on Maven Central: one Gradle plugin, two library variants, three converters

Six packages are available on Maven Central, all under the group ID de.jensklingenberg.ktorfit. The Ktorfit Gradle Plugin, with artifact ID de.jensklingenberg.ktorfit.gradle.plugin, registers the KSP processor into a Gradle build. The standard runtime dependency is ktorfit-lib. A lighter alternative, ktorfit-lib-light, serves projects that do not need the full dependency set; the documentation site at https://foso.github.io/Ktorfit/ is the reference for which dependencies each variant drops.

The 3 optional converter packages handle different response types. ktorfit-converters-flow adds Kotlin Flow support for API responses that are treated as streams or deferred values. ktorfit-converters-call adds Call wrappers for cancellable or deferred responses. ktorfit-converters-response adds a Response wrapper that carries the HTTP status code and headers alongside the body.

Including any of the 3 converter packages is optional: projects that return only plain types or suspend functions from annotated interfaces may not need any of them. Each converter package has its own Maven Central artifact, so only the response types a project actually uses need to be declared as dependencies. All 6 packages and their current versions are linked from the README's package table to their respective Maven Central pages.

Setting up Ktorfit: the Gradle plugin, the library, and the documentation site

The README does not include inline Gradle configuration. It points to a dedicated setup page at https://foso.github.io/Ktorfit/installation/ for the actual build configuration, which covers the Gradle plugin declaration, the KSP plugin integration, and the dependency on either ktorfit-lib or ktorfit-lib-light.

From the repository structure, Ktorfit is itself a multi-module Gradle project with separate directories for the Gradle plugin, the KSP processor, the compiler plugin, the core library, and the converters. The top-level build uses build.gradle.kts, settings.gradle.kts and a build-logic/ directory for shared build configuration, a common structure for multi-module Kotlin projects published on Maven Central.

The 2 example projects at example/AndroidOnlyExample/ and example/MultiplatformExample/ are the repository's reference for how the plugin and library wire together in practice. For teams evaluating Ktorfit, the MultiplatformExample is the relevant reference for shared-code projects, while AndroidOnlyExample focuses on the Android target specifically. The example directories are in the repository but their contents are not reproduced in the README.

For the change history, the file docs/CHANGELOG.md inside the repository is what the README links to under its latest changes reference.

Platform list discrepancy: README says Linux, description adds Native and WasmJs

The platform list appears twice in the project's own documentation, and the two lists are not the same. The GitHub repository description names these targets: Android, iOS, Js, Jvm, Native and WasmJs. The README introduction lists them as Android, iOS, Js, Jvm and Linux. These are different in 2 places.

First, the description uses Native, meaning Kotlin/Native, the umbrella target that covers Linux, macOS, Windows, iOS-native and other operating systems, while the README uses the specific term Linux. Kotlin/Native is broader than Linux; substituting one for the other is not precise. Second, the description adds WasmJs as a supported target, a platform that the README introduction omits entirely.

For teams targeting Apple Silicon Macs, embedded systems, or WebAssembly, the gap matters. WasmJs support in Ktor itself has been in active development, and whether Ktorfit's code generation handles it fully is a question the documentation site needs to answer. The project topics include android, kotlin-native, kotlinjs, kotlin-multiplatform-mobile and ksp, which align more closely with the description's target list than with the README introduction's. Until the documentation site explicitly confirms each target's support status, teams targeting Kotlin/Native platforms beyond Linux should verify compatibility before committing to Ktorfit.

Compile-time code generation versus Retrofit's runtime dynamic proxies

Retrofit processes interface annotations by creating Java dynamic proxies at runtime. When a method on a Retrofit interface is called, the proxy intercepts the call and constructs the HTTP request from the annotation metadata at that moment. The entire path from annotation to HTTP request runs through Java's reflection system on every call.

Ktorfit takes a different path by using KSP to generate concrete implementation classes during the build, before any code runs. At runtime, the generated class is instantiated directly with no reflection overhead for the interface methods themselves. The tradeoff is that KSP adds a code generation step to every build that touches the annotated interfaces, and changing an interface definition requires that step to run again.

For Android-only projects already using Retrofit and not planning to expand to other Kotlin targets, Retrofit has an established ecosystem: extensive documentation, community libraries and battle-tested behavior in production Android apps. Ktorfit becomes relevant when the same API interface definition must work across more than one Kotlin target, specifically when that definition lives in a shared common module and the Android target is only one of several.

Where Ktorfit requires more than annotation processing: Ktor client setup

Ktorfit generates the code that calls Ktor clients, but it does not bundle a Ktor client. Each platform target requires its own Ktor engine dependency and configuration. A project targeting Android and iOS needs the Ktor Android engine and the Ktor Darwin engine declared separately, each with its configuration, and these are independent of the Ktorfit setup. An error in the Ktor engine configuration produces a runtime failure, not a build failure from Ktorfit.

For teams new to Ktor, this adds a second learning surface alongside the Ktorfit annotation API. Ktor's client documentation is separate from Ktorfit's documentation, and the amount of platform-specific configuration required varies by target. The compatibility table at https://foso.github.io/Ktorfit/#compatibility is the reference for which Ktor client versions align with each Ktorfit build, since the two projects version independently.

Ktorfit is not appropriate for projects that need to keep a non-Ktor HTTP client. The generated code is tied to Ktor, and there is no adapter layer that targets OkHttp, Volley or another client directly. Adopting Ktorfit on a project already using one of those clients means replacing the HTTP layer entirely.

Documentation built with MkDocs and Python, separate from the Kotlin build

Ktorfit's documentation site at https://foso.github.io/Ktorfit/ is built with MkDocs, a Python documentation generator, rather than a Kotlin-based documentation tool. The pyproject.toml at the repository root specifies the Python dependencies: mkdocs==1.6.1, mkdocs-material==9.5.47, mkdocs-git-revision-date-localized-plugin==0.14.0, mkdocs-minify-plugin==0.8.0 and mkdocs-macros-plugin==1.5.0. The Python runtime requires version 3.10 or newer.

This matters for contributors who want to run the documentation site locally. Building the docs requires a Python 3.10+ environment with these specific pinned versions, entirely separate from the Gradle and Kotlin tools needed to build the library. The documentation site is where the API behavior, installation steps and compatibility tables live; these pages are not reproduced in the repository's README.

Ktorfit is distributed under Apache-2.0, with all packages on Maven Central under the group ID de.jensklingenberg.ktorfit. Feedback and bug reports go to the GitHub issue tracker, and the README also lists the maintainer's Twitter account for questions.

Editorial conclusion

Ktorfit is the right choice for Kotlin Multiplatform projects where a shared API interface definition must compile for Android, iOS, JVM, JavaScript and Linux targets together. For Android-only projects not planning to add other Kotlin targets, the KSP build step and Ktor dependency add complexity without multiplatform benefit. Before adopting, verify the compatibility between the Ktor client and Ktorfit builds using the table at https://foso.github.io/Ktorfit/#compatibility, and check that the Gradle plugin and KSP versions align for your project.

Frequently asked questions

Official sources

1. Foso/Ktorfit on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases