Kotlin Academy · Lesson

kotlinx.serialization Setup

Add the plugin.

kotlinx.serialization Setup is a free Kotlin Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What is kotlinx.serialization?

kotlinx.serialization is the official Kotlin library for converting objects to and from formats like JSON.

Pure Kotlin, multiplatform-ready
Compile-time code generation (no reflection)
Maintained by JetBrains

It works with a compiler plugin plus a runtime library.

Why a Compiler Plugin?

Unlike reflection-based libraries, kotlinx.serialization generates serializers at compile time.

Faster, no runtime reflection cost
Works on Kotlin/Native and JS where reflection is limited
Type-safe and verified by the compiler

This is why you must apply the kotlin-serialization plugin, not just add a dependency.

Applying the Plugin (Kotlin DSL)

In build.gradle.kts apply the serialization plugin with the same version as your Kotlin plugin.

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

Adding the Runtime Dependency

The plugin generates code, but you also need the JSON runtime library.

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

Version Alignment Matters

The plugin.serialization version must match your Kotlin compiler version. The runtime library has its own independent version.

Plugin version = Kotlin version (e.g. 2.0.0)
Runtime version is separate (e.g. 1.7.1)

Mismatched plugin/Kotlin versions cause cryptic build errors.

Other Formats

JSON is the most common, but kotlinx.serialization supports more formats via extra artifacts:

kotlinx-serialization-json — JSON
kotlinx-serialization-cbor — CBOR binary
kotlinx-serialization-protobuf — Protocol Buffers

You add only the format artifacts you need.

Groovy DSL Equivalent

If your project uses Groovy build.gradle instead of Kotlin DSL, the setup looks like this.

// build.gradle (Groovy)
plugins {
    id 'org.jetbrains.kotlin.jvm' version '2.0.0'
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0'
}

dependencies {
    implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1'
}

The Json Entry Point

Once set up, you use the Json object from kotlinx.serialization.json as your main entry point for encoding and decoding.

import kotlinx.serialization.json.Json

val format = Json
// format.encodeToString(...) / format.decodeFromString(...)

A Minimal Working Snippet

Here is the smallest end-to-end example once the plugin and runtime are configured.

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class City(val name: String, val population: Int)

fun main() {
    val city = City("Istanbul", 15000000)
    val json = Json.encodeToString(city)
    println(json)
}

Multiplatform Setup

In a Kotlin Multiplatform project, add the runtime to commonMain so all targets share it.

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.1")
        }
    }
}

Common Setup Mistakes

Watch out for these frequent issues:

Forgetting the plugin — you get Serializer has not been found
Plugin version not matching Kotlin version
Adding the runtime but not the plugin (or vice versa)
Missing import of encodeToString

Quick Check

Why does kotlinx.serialization require a Gradle compiler plugin?

Recap

You set up kotlinx.serialization by:

Applying the kotlin("plugin.serialization") plugin matching your Kotlin version
Adding the kotlinx-serialization-json runtime dependency
Using the Json object as the entry point

Next you'll annotate model classes with @Serializable.

Frequently asked questions

Is the “kotlinx.serialization Setup” lesson free?

Yes — the full text of “kotlinx.serialization Setup” is free to read here on the web, and the Kotlin Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Academy course, upgrade to CoddyKit PRO.

What will I learn in “kotlinx.serialization Setup”?

Add the plugin. You practise Kotlin Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Kotlin Academy?

No prior experience is required. Kotlin Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “kotlinx.serialization Setup” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Kotlin Academy lesson?

Yes. Every Kotlin Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Kotlin Academy