or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-serialization

Gradle plugin for kotlinx.serialization library that enables serialization support in Kotlin projects

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-serialization@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-serialization@2.2.0

index.mddocs/

Kotlin Serialization Gradle Plugin

The kotlin-serialization Gradle plugin enables kotlinx.serialization support in Kotlin projects by automatically applying the Kotlin serialization compiler plugin. This plugin handles the complex setup required to enable compile-time code generation for serializable classes, providing seamless integration with Kotlin multiplatform projects and a simple way to enable serialization support through Gradle's plugin system.

Package Information

  • Package Name: org.jetbrains.kotlin.plugin.serialization
  • Package Type: maven (Gradle plugin)
  • Language: Kotlin
  • Installation: Apply via Gradle plugins block

Core Imports

// In build.gradle.kts - apply the plugin
plugins {
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
}

Basic Usage

// 1. Apply the plugin in build.gradle.kts
plugins {
    kotlin("jvm") version "2.2.0"
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
}

// 2. Add kotlinx.serialization dependency
dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}

// 3. Use serialization in your Kotlin code
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class User(val name: String, val age: Int)

fun main() {
    val user = User("Alice", 30)
    val json = Json.encodeToString(user)
    println(json) // {"name":"Alice","age":30}
    
    val parsed = Json.decodeFromString<User>(json)
    println(parsed) // User(name=Alice, age=30)
}

Architecture

The plugin follows the standard Kotlin compiler plugin integration pattern:

  • Plugin Application: Gradle applies the plugin via plugin ID resolution
  • Compiler Integration: Plugin automatically configures Kotlin compiler to include serialization plugin
  • Artifact Resolution: Plugin handles dependency resolution for both JVM/Android and Native targets
  • Zero Configuration: Plugin requires no additional configuration - it automatically applies to all Kotlin compilations

Capabilities

Plugin Application

Apply the serialization plugin to enable kotlinx.serialization in your Kotlin project.

// Plugin ID
id("org.jetbrains.kotlin.plugin.serialization")

Compiler Plugin Integration

The plugin automatically integrates with the Kotlin compiler through the SerializationGradleSubplugin implementation.

package org.jetbrains.kotlinx.serialization.gradle

class SerializationGradleSubplugin : KotlinCompilerPluginSupportPlugin {
    
    companion object {
        const val SERIALIZATION_GROUP_NAME = "org.jetbrains.kotlin"
        const val SERIALIZATION_ARTIFACT_NAME = "kotlin-serialization-compiler-plugin-embeddable"
        const val SERIALIZATION_ARTIFACT_UNSHADED_NAME = "kotlin-serialization-compiler-plugin"
    }
    
    /**
     * Always returns true - the plugin applies to all Kotlin compilations.
     */
    override fun isApplicable(kotlinCompilation: KotlinCompilation<*>): Boolean = true
    
    /**
     * Returns empty list of sub-plugin options (no configuration required).
     */
    override fun applyToCompilation(
        kotlinCompilation: KotlinCompilation<*>
    ): Provider<List<SubpluginOption>> = 
        kotlinCompilation.target.project.provider { emptyList() }
    
    /**
     * Returns the compiler plugin artifact for JVM/Android targets (embeddable version).
     */
    override fun getPluginArtifact(): SubpluginArtifact =
        SubpluginArtifact(SERIALIZATION_GROUP_NAME, SERIALIZATION_ARTIFACT_NAME)
    
    /**
     * Returns the compiler plugin artifact for Native targets (unshaded version).
     */
    override fun getPluginArtifactForNative(): SubpluginArtifact =
        SubpluginArtifact(SERIALIZATION_GROUP_NAME, SERIALIZATION_ARTIFACT_UNSHADED_NAME)
    
    /**
     * Returns the compiler plugin ID: "org.jetbrains.kotlinx.serialization"
     */
    override fun getCompilerPluginId() = "org.jetbrains.kotlinx.serialization"
}

Plugin Constants

Access to internal plugin constants for advanced use cases.

companion object {
    /** Maven group ID for serialization compiler plugin artifacts */
    const val SERIALIZATION_GROUP_NAME = "org.jetbrains.kotlin"
    
    /** Artifact name for JVM/Android compiler plugin (embeddable version) */
    const val SERIALIZATION_ARTIFACT_NAME = "kotlin-serialization-compiler-plugin-embeddable"
    
    /** Artifact name for Native compiler plugin (unshaded version) */
    const val SERIALIZATION_ARTIFACT_UNSHADED_NAME = "kotlin-serialization-compiler-plugin"
}

Compiler Plugin ID

The plugin registers with the Kotlin compiler using a specific plugin ID.

/**
 * The compiler plugin ID used by Kotlin compiler: "org.jetbrains.kotlinx.serialization"
 */
fun getCompilerPluginId(): String = "org.jetbrains.kotlinx.serialization"

Types

/**
 * Main plugin implementation class that integrates with Kotlin compiler plugin system.
 * Located in org.jetbrains.kotlinx.serialization.gradle package.
 */
class SerializationGradleSubplugin : KotlinCompilerPluginSupportPlugin

/**
 * Represents a sub-plugin artifact with group and artifact coordinates.
 * Part of Kotlin Gradle Plugin API.
 */
class SubpluginArtifact(
    val groupId: String,
    val artifactId: String
)

/**
 * Configuration option interface from Kotlin Gradle Plugin API.
 * This plugin returns empty list (no configuration options).
 */
interface SubpluginOption

/**
 * Kotlin compilation interface from Kotlin Gradle Plugin API.
 * The plugin applies to all compilation types automatically.
 */
interface KotlinCompilation<*>

/**
 * Gradle Provider interface for lazy evaluation.
 */
interface Provider<T>

Plugin Usage Patterns

Multiplatform Projects

// build.gradle.kts for multiplatform project
plugins {
    kotlin("multiplatform") version "2.2.0"
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
}

kotlin {
    jvm()
    js(IR) {
        browser()
        nodejs()
    }
    
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
            }
        }
    }
}

Android Projects

// build.gradle.kts for Android project
plugins {
    id("com.android.application")
    kotlin("android") version "2.2.0"
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
}

Version Catalog Usage

# gradle/libs.versions.toml
[versions]
kotlin = "2.2.0"
kotlinx-serialization = "1.6.0"

[plugins]
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

[libraries]
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
// build.gradle.kts using version catalog
plugins {
    alias(libs.plugins.kotlin.serialization)
}

dependencies {
    implementation(libs.kotlinx.serialization.json)
}

Error Handling

The plugin typically fails silently if the Kotlin plugin is not applied or if there are version mismatches. Common issues:

  • Missing Kotlin plugin: Ensure kotlin("jvm"), kotlin("multiplatform"), or kotlin("android") is applied before the serialization plugin
  • Version mismatch: Use the same version for the Kotlin plugin and serialization plugin
  • Missing runtime dependency: Add kotlinx-serialization-json or other format dependencies to your project

No custom error handling is exposed by the plugin itself - it relies on Gradle's standard plugin resolution and Kotlin's compiler plugin mechanisms.