0
# Kotlin Serialization Gradle Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin.plugin.serialization
7
- **Package Type**: maven (Gradle plugin)
8
- **Language**: Kotlin
9
- **Installation**: Apply via Gradle plugins block
10

11
## Core Imports
12

13
```kotlin
14
// In build.gradle.kts - apply the plugin
15
plugins {
16
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
17
}
18
```
19

20

21
## Basic Usage
22

23
```kotlin
24
// 1. Apply the plugin in build.gradle.kts
25
plugins {
26
    kotlin("jvm") version "2.2.0"
27
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
28
}
29

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

35
// 3. Use serialization in your Kotlin code
36
import kotlinx.serialization.*
37
import kotlinx.serialization.json.*
38

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

42
fun main() {
43
    val user = User("Alice", 30)
44
    val json = Json.encodeToString(user)
45
    println(json) // {"name":"Alice","age":30}
46
    
47
    val parsed = Json.decodeFromString<User>(json)
48
    println(parsed) // User(name=Alice, age=30)
49
}
50
```
51

52
## Architecture
53

54
The plugin follows the standard Kotlin compiler plugin integration pattern:
55

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

61
## Capabilities
62

63
### Plugin Application
64

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

67
```kotlin { .api }
68
// Plugin ID
69
id("org.jetbrains.kotlin.plugin.serialization")
70
```
71

72
### Compiler Plugin Integration
73

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

76
```kotlin { .api }
77
package org.jetbrains.kotlinx.serialization.gradle
78

79
class SerializationGradleSubplugin : KotlinCompilerPluginSupportPlugin {
80
    
81
    companion object {
82
        const val SERIALIZATION_GROUP_NAME = "org.jetbrains.kotlin"
83
        const val SERIALIZATION_ARTIFACT_NAME = "kotlin-serialization-compiler-plugin-embeddable"
84
        const val SERIALIZATION_ARTIFACT_UNSHADED_NAME = "kotlin-serialization-compiler-plugin"
85
    }
86
    
87
    /**
88
     * Always returns true - the plugin applies to all Kotlin compilations.
89
     */
90
    override fun isApplicable(kotlinCompilation: KotlinCompilation<*>): Boolean = true
91
    
92
    /**
93
     * Returns empty list of sub-plugin options (no configuration required).
94
     */
95
    override fun applyToCompilation(
96
        kotlinCompilation: KotlinCompilation<*>
97
    ): Provider<List<SubpluginOption>> = 
98
        kotlinCompilation.target.project.provider { emptyList() }
99
    
100
    /**
101
     * Returns the compiler plugin artifact for JVM/Android targets (embeddable version).
102
     */
103
    override fun getPluginArtifact(): SubpluginArtifact =
104
        SubpluginArtifact(SERIALIZATION_GROUP_NAME, SERIALIZATION_ARTIFACT_NAME)
105
    
106
    /**
107
     * Returns the compiler plugin artifact for Native targets (unshaded version).
108
     */
109
    override fun getPluginArtifactForNative(): SubpluginArtifact =
110
        SubpluginArtifact(SERIALIZATION_GROUP_NAME, SERIALIZATION_ARTIFACT_UNSHADED_NAME)
111
    
112
    /**
113
     * Returns the compiler plugin ID: "org.jetbrains.kotlinx.serialization"
114
     */
115
    override fun getCompilerPluginId() = "org.jetbrains.kotlinx.serialization"
116
}
117
```
118

119
### Plugin Constants
120

121
Access to internal plugin constants for advanced use cases.
122

123
```kotlin { .api }
124
companion object {
125
    /** Maven group ID for serialization compiler plugin artifacts */
126
    const val SERIALIZATION_GROUP_NAME = "org.jetbrains.kotlin"
127
    
128
    /** Artifact name for JVM/Android compiler plugin (embeddable version) */
129
    const val SERIALIZATION_ARTIFACT_NAME = "kotlin-serialization-compiler-plugin-embeddable"
130
    
131
    /** Artifact name for Native compiler plugin (unshaded version) */
132
    const val SERIALIZATION_ARTIFACT_UNSHADED_NAME = "kotlin-serialization-compiler-plugin"
133
}
134
```
135

136
### Compiler Plugin ID
137

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

140
```kotlin { .api }
141
/**
142
 * The compiler plugin ID used by Kotlin compiler: "org.jetbrains.kotlinx.serialization"
143
 */
144
fun getCompilerPluginId(): String = "org.jetbrains.kotlinx.serialization"
145
```
146

147
## Types
148

149
```kotlin { .api }
150
/**
151
 * Main plugin implementation class that integrates with Kotlin compiler plugin system.
152
 * Located in org.jetbrains.kotlinx.serialization.gradle package.
153
 */
154
class SerializationGradleSubplugin : KotlinCompilerPluginSupportPlugin
155

156
/**
157
 * Represents a sub-plugin artifact with group and artifact coordinates.
158
 * Part of Kotlin Gradle Plugin API.
159
 */
160
class SubpluginArtifact(
161
    val groupId: String,
162
    val artifactId: String
163
)
164

165
/**
166
 * Configuration option interface from Kotlin Gradle Plugin API.
167
 * This plugin returns empty list (no configuration options).
168
 */
169
interface SubpluginOption
170

171
/**
172
 * Kotlin compilation interface from Kotlin Gradle Plugin API.
173
 * The plugin applies to all compilation types automatically.
174
 */
175
interface KotlinCompilation<*>
176

177
/**
178
 * Gradle Provider interface for lazy evaluation.
179
 */
180
interface Provider<T>
181
```
182

183
## Plugin Usage Patterns
184

185
### Multiplatform Projects
186

187
```kotlin
188
// build.gradle.kts for multiplatform project
189
plugins {
190
    kotlin("multiplatform") version "2.2.0"
191
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
192
}
193

194
kotlin {
195
    jvm()
196
    js(IR) {
197
        browser()
198
        nodejs()
199
    }
200
    
201
    sourceSets {
202
        val commonMain by getting {
203
            dependencies {
204
                implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
205
            }
206
        }
207
    }
208
}
209
```
210

211
### Android Projects
212

213
```kotlin
214
// build.gradle.kts for Android project
215
plugins {
216
    id("com.android.application")
217
    kotlin("android") version "2.2.0"
218
    id("org.jetbrains.kotlin.plugin.serialization") version "2.2.0"
219
}
220

221
dependencies {
222
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")
223
}
224
```
225

226
### Version Catalog Usage
227

228
```toml
229
# gradle/libs.versions.toml
230
[versions]
231
kotlin = "2.2.0"
232
kotlinx-serialization = "1.6.0"
233

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

237
[libraries]
238
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }
239
```
240

241
```kotlin
242
// build.gradle.kts using version catalog
243
plugins {
244
    alias(libs.plugins.kotlin.serialization)
245
}
246

247
dependencies {
248
    implementation(libs.kotlinx.serialization.json)
249
}
250
```
251

252
## Error Handling
253

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

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

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