Configuration

gRPC integration is available in an experimental state. The artifacts are published separately in our Space repository.

Dependencies configuration

Below is an example of a project setup.

settings.gradle.kts:

            pluginManagement {
                repositories {
                    gradlePluginPortal()
                    mavenCentral()
                    maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc")
                }
            }
        

build.gradle.kts:

            plugins {
                kotlin("jvm") version "2.2.0"
                id("org.jetbrains.kotlinx.rpc.plugin") version "<version>"
            }

            repositories {
                mavenCentral()
                maven("https://maven.pkg.jetbrains.space/public/p/krpc/grpc")
            }

            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-rpc-grpc-core:<version>")
                implementation("ch.qos.logback:logback-classic:1.5.16")
                implementation("io.grpc:grpc-netty:1.73.0")
            }
        

Here <version> comes from the badge above.

Working with proto-files

The minimum required configuration looks like this:

This enables code generation for your .proto files. Special source sets are created for them:

main and test - source sets for Kotlin/JVM projects. Default source directories are src/main/proto and src/test/proto.
jvmMain and jvmTest - source sets for Kotlin/Multiplatform projects. Default source directories are src/jsmMain/proto and src/jvmTest/proto.
These will change to src/commonMain/proto and src/commonTest/proto in the future.
Android source set support is not available yet but will be included in a future release.

All source sets are generated automatically and available via the protoSourceSets Gradle Project extension:

            protoSourceSets {
                // for Kotlin/JVM projects
                main {
                    proto {
                        // SourceDirectorySet for .proto files
                        include("**/main.proto") // optional filters
                        exclude("**/excluded.proto")
                    }
                }
                test { }

                // for Kotlin/Multiplatform projects
                jvmMain { }
                jvmTest { }
            }
        

By default, the following source directories are generated:

java - protobuf Java declarations, attached to java sources.
grpc-java - gRPC Java declarations, attached to java sources.
grpc-kotlin - gRPC Kotlin wrappers for Java, attached to kotlin sources.
kotlin-multiplatform - wrappers for all of the above, attached to kotlin sources.

Limitations

Source set hierarchy is not supported, and we have no plans to support it. That means, for example, that you can't have jsMain and jsTest source sets for proto files. The same applies for native and Wasm targets. Currently, .proto files are only supported in the jvmMain and jvmTest source sets. (Later to be replaced with commonMain and commonTest)

If you have a use case for other source sets and a hierarchy, please report it.

Protoc plugins

To generate code, we use protoc plugins. By default, we use the following plugins:

protobuf-java - Buf's version of the official Java plugin.
grpc-java - Buf's version of the official gRPC Java plugin.
grpc-kotlin - Buf's version of the official gRPC Kotlin plugin.
kotlin-multiplatform - out own protoc plugin.

You can configure the plugins in the rpc block:

            rpc {
                grpc {
                    // configure plugins here
                    protocPlugins {
                        kotlinMultiplatform { }
                        protobufJava { }
                        grpcJava { }
                        grpcKotlin { }

                        create("myPlugin") { }
                    }
                }
            }
        

protocPlugins is a NamedDomainObjectContainer<ProtocPlugin>, which allows you to add your own plugins.

Each plugin is represented by a ProtocPlugin and can be configured like this:

            // Or use protocPlugins.kotlinMultiplatform for default plugins
            protocPlugins.create("myPlugin") {
                isJava = true // add generated code to the java source set

                // Add plugin options
                options.put("myOption")
                options.put("myOption1", "myValue")

                // Plugin can be local or remote

                // For a local plugin
                local {
                    // Path to the plugin executable
                    executor("java", "-jar", "myPlugin.jar")
                    // or
                    javaJar("myPlugin.jar") // uses java.home
                    // or
                    javaJar("myPlugin.jar", "path/to/my/java")
                    // or
                    executor("myCustomExe.exe")
                }

                // For a remote plugin
                remote {
                    // Buf's BSR locator
                    locator = "buf.build/grpc/go"
                }

                // Additional Buf configuration options:
                strategy = ProtocPlugin.Strategy.All
                includeImports = false
                includeWkt = false
                types = listOf("my.package.MyType")
                excludeTypes = listOf("my.package.NotMyType")
            }
        

Buf's plugin configuration options:

strategy: strategy — All or Directory
includeImports: includeImports — true or false
includeWkt: includeWkt — true or false
types: types — a list of types to generate.
excludeTypes: excludeTypes — a list of types to exclude from generation.

Once a plugin is added to the protocPlugins container, it can be used in a source set:

            protoSourceSets {
                jvmMain {
                    protocPlugin(rpc.grpc.protocPlugins.named("myPlugin"))
                }
            }
        

Buf

As you may already notice, we use Buf — a tool for managing and building Protobuf schemas. We use its CLI to execute tasks like code generation.

Generated Workspace

To improve the developer experience, we introduce the concept of a generated workspace. It's a directory that contains all the necessary files for Buf to work:

Filtered .proto files
Generated buf.yaml file
Generated buf.gen.yaml file
Automatically managed imports from a main source set to a test source set, making imports intuitive.

This workspace is created automatically for each source set and can be found in the build/protoBuild directory. You don't need to do anything with it, unless you want to customize it.

Tasks

If your project is configured to use gRPC, the following tasks will be generated:

generateBufYaml<sourceSet> — generates buf.yaml

Type: kotlinx.rpc.buf.tasks.GenerateBufYaml
generateBufGenYaml<sourceSet> — generates buf.gen.yaml

Type: kotlinx.rpc.buf.tasks.GenerateBufGenYaml
processProtoFiles<sourceSet> — copies proto files to the workspace directory

Type: kotlinx.rpc.proto.ProcessProtoFiles
processProtoFilesImport<sourceSet> — copies import proto files to the workspace directory

Type: kotlinx.rpc.proto.ProcessProtoFiles
bufGenerate<sourceSet> — runs buf generate command.

Type: kotlinx.rpc.buf.tasks.BufGenerateTask

To configure Buf, use the buf block:

                rpc {
                    grpc {
                        buf {
                            // Configure Buf
                            logFormat = BufExtenstion.LogFormat.Text
                            timeout = 60.seconds

                            generate {
                                // Configure Buf generate

                                includeImports = false
                                includeWkt = false
                                errorFormat = BufGenerateExtenstion.ErrorFormat.Text
                            }
                        }
                    }
                }
            

General configuration options:

logFormat: logFormat — either Text, Color, Json or Default
timeout: timeout — timeout for the buf commands, always converted to whole seconds
--debug: Running Gradle with --debug enables Buf's --debug option as well.

buf generate configuration options:

includeImports: includeImports — true or false
includeWkt: includeWkt — true or false
errorFormat: errorFormat — either Text, Json, Msvs, Junit, GithubActions or Default

Custom tasks

Currently, we only support generate tasks. However, because of Buf's capabilities for managing .proto files, like linting and detection of breaking changes, we provide a way to create custom Buf tasks.

To create a custom task, extend the kotlinx.rpc.buf.tasks.BufExecTask class. You don't need to define a @TaskAction; just a set of arguments and a command to execute.

You can register the task in two ways:

A workspace task (recommended):
rpc.grpc.buf.tasks { val provider = registerWorkspaceTask<MyBufLintTask>("lint") { // configure task here } // bufLintMain, or bufLintJvmMain for KMP projects provider.mainTask // bufLintTest, or bufLintJvmTest for KMP projects provider.testTask }
These tasks can be executed on a generated workspace for all proto source sets.
These tasks are not plugged into the Gradle build cycle, so you must run them manually
A regular task:
project.registerBufExecTask<MyBufLintTask>( name = "bufLint", workingDir = workingDirProvider, ) { // configure task here }
It is a standard Gradle task that has access to the Buf's executable and some predefined properties.

Last modified: 04 August 2025