Get started

kotlinx.rpc is a multiplatform Kotlin library that provides its users with tools to perform Remote Procedure Calls (RPC) using Kotlin language constructs with as easy setup as possible. The library is transport agnostic by design, so most transfer mechanisms can be used under the hood: WebSockets, HTTP Requests, gRPC, etc.

What this library is and what it is not

It is important to understand that this library is a set of tools and APIs gathered in one place with a goal of providing a great user experience when working with RPC systems in Kotlin Multiplatform projects. kotlinx.rpc provides its own in-house new RPC protocol, but it is not a library solely focused on this protocol.

The combination of Kotlin Multiplatform technology and RPC concept opens an opportunity to provide exceptional user experience while creating client-server applications, and we will create technologies that will embrace the concept in this library. This will include our own in-house RPC protocol with the focus on KMP projects, as well as integrations with other technologies, including but not limited to gRPC.

Installation

Before adding kotlinx.rpc dependencies, you need to configure your project with Gradle.

Configure the repositories

To be able to add dependencies for kotlinx.rpc artifacts, you need to define a repository from which they will be consumed.

Add the following repositories in your build.gradle.kts file:

                repositories {
                    // for kotlinx.rpc dependencies
                    maven(url = "https://maven.pkg.jetbrains.space/public/p/krpc/maven")
                    // for other dependencies, like Ktor
                    mavenCentral()
                }
            

In your settings.gradle.kts file, specify a repository for plugins to be consumed from:

                pluginManagement {
                    repositories {
                        // kotlinx.rpc plugins will be downloaded from here
                        maven(url = "https://maven.pkg.jetbrains.space/public/p/krpc/maven")
                        // other plugins, like Kotlin, will be downloaded from here
                        gradlePluginPortal()
                    }
                }
            

Add runtime dependencies

kotlinx.rpc provides you with runtime dependencies (also called artifacts). To use these dependencies, you first need to define them in your project's build.gradle.kts file:

                        dependencies {
                            // example kotlinx.rpc artifacts
                            implementation("org.jetbrains.kotlinx:kotlinx-rpc-runtime-client:1.9.24-0.1.0")
                            implementation("org.jetbrains.kotlinx:kotlinx-rpc-runtime-server:1.9.24-0.1.0")
                        }
                    

This adds the APIs needed to work with both client and server code using kotlinx.rpc.

For a full example, see the single-module Ktor app example.

                        kotlin {
                            // source sets can be any other supported, ios and jvm are chosen just for an example
                            sourceSets {
                                iosMain {
                                    // let's say that we have code for the client in iosMain sources set
                                    implementation("org.jetbrains.kotlinx:kotlinx-rpc-runtime-client:1.9.24-0.1.0")
                                }

                                jvmMain {
                                    // let's say that we have code for the server in jvmMain sources set
                                    implementation("org.jetbrains.kotlinx:kotlinx-rpc-runtime-server:1.9.24-0.1.0")
                                }
                            }
                        }
                    

Here we define dependencies for iosMain and jvmMain source sets, but it can be any other source set that you may want to have. Also, you may want to split your application into several modules, so that you have a server in one module and a client in another.

For a full example, see the Ktor web app example. In this example you will find usage of Gradle version catalogs, so the dependency declaration may look like this:

                        # gradle / libs.versions.toml
                        [versions]
                        kotlinx - rpc = "1.9.24-0.1.0"

                        [libraries]
                        kotlinx - rpc - client = {
                            module =
                                "org.jetbrains.kotlinx:kotlinx-rpc-runtime-client", version.ref = "kotlinx-rpc"
                        }
                    

                        // build.gradle.kts
                        dependecies {
                            implementation(libs.kotlinx.rpc.client)
                        }
                    

Add plugin dependencies

kotlinx.rpc provides two Gradle plugins:

To add a plugin to your project, you need to define the following in your build.gradle.kts:

                plugins {
                    id("org.jetbrains.kotlinx.rpc.plugin") version "0.1.0"
                }
            

Add serialization dependency

kotlinx.rpc requires you to add kotlinx.serialization Gradle plugin to your project.

                plugins {
                    kotlin("jvm") version "1.9.24"
                    kotlin("plugin.serialization") version "1.9.24"
                }
            

To learn how to configure serialization in kotlinx.rpc, see serialization DSL.

Last modified: 13 June 2024