Skip to content

Documentation rewrite - Get started page #3059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Nov 12, 2025
Merged

Documentation rewrite - Get started page #3059

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e7ef54f
feat: adding the get started page
daniCsorbaJB Aug 11, 2025
c8e2920
implementing review comments from first round of review
daniCsorbaJB Aug 14, 2025
c31a5b7
implementing second round of comments for the get started page
daniCsorbaJB Oct 17, 2025
537ff6b
fix: using slightly smoother wording for R8
daniCsorbaJB Oct 17, 2025
68f4be6
update: clarifying Bazel support and addressing last comment about R8
daniCsorbaJB Oct 21, 2025
f8ce157
update: implementing TWr comments from Sarah
daniCsorbaJB Nov 10, 2025
5d16f9b
update: refining R8 related comments slightly
daniCsorbaJB Nov 11, 2025
2c0ce70
adding final version for whats next link
daniCsorbaJB Nov 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 121 additions & 73 deletions docs-website/topics/serialization-get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,15 @@

[Serialization](serialization.md) converts objects into a format that can be stored or transmitted and later reconstructed.

Kotlin serialization supports multiple formats.
This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization and how to serialize and deserialize objects in JSON format.

## Add plugins and dependencies for Kotlin serialization
## Add plugins and dependencies for Kotlin serialization to your project

To include the `kotlinx.serialization` library in your project, add the corresponding plugin and dependency configuration based on your build tool.

> To set up the Kotlin compiler plugin for Bazel, see the example provided in the [rules_kotlin repository](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization).
>
{style="tip"}

### Gradle

Add the following dependency to your `build.gradle(.kts)` file:
To include the `kotlinx.serialization` library in your project, add the corresponding plugin and dependency configuration based on your build tool:

<tabs>
<tab id="kotlin" title="Kotlin">
<tab id="kotlin" title="Gradle Kotlin">

```kotlin
// build.gradle.kts
Expand All @@ -31,8 +24,7 @@ dependencies {
```

</tab>

<tab id="groovy" title="Groovy">
<tab id="groovy" title="Gradle Groovy">

```groovy
// build.gradle
Expand All @@ -46,72 +38,65 @@ dependencies {
```

</tab>
<tab id="maven" title="Maven">

```xml
<!-- pom.xml -->
<properties>
<kotlin.version>%kotlinVersion%</kotlin.version>
<serialization.version>%serializationVersion%</serialization.version>
</properties>

<build>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<executions>
<execution>
<id>compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<compilerPlugins>
<plugin>kotlinx-serialization</plugin>
</compilerPlugins>
</configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-serialization</artifactId>
<version>${kotlin.version}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>

<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-json</artifactId>
<version>${serialization.version}</version>
</dependency>
</dependencies>
```

</tab>
</tabs>

### Maven

Add the serialization plugin and library to your `pom.xml` file:

1. Specify the Kotlin and serialization version in the `<properties>` section:

```xml
<properties>
<kotlin.version>%kotlinVersion%</kotlin.version>
<serialization.version>%serializationVersion%</serialization.version>
</properties>
```

2. Add the Kotlin serialization Maven plugin to the `<build>` section:

```xml
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<executions>
<execution>
<id>compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<compilerPlugins>
<plugin>kotlinx-serialization</plugin>
</compilerPlugins>
</configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-serialization</artifactId>
<version>${kotlin.version}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
```

3. Add the JSON serialization library dependency to the `<dependencies>` section:

```xml
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-json</artifactId>
<version>${serialization.version}</version>
</dependency>
</dependencies>
```
> To set up the Kotlin compiler plugin for Bazel, see the example provided in the [rules_kotlin repository](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization).
>
{style="tip"}

### Add the Kotlin serialization library to a multiplatform project

To use Kotlin serialization in multiplatform projects, add the JSON serialization library dependency to your common source set:
To use Kotlin serialization for JSON in multiplatform projects, add the JSON serialization library dependency to your common source set:

```kotlin
commonMain {
Expand All @@ -121,6 +106,69 @@ commonMain {
}
```

This dependency automatically includes the core serialization library as well.

### Configure R8 for Kotlin serialization in Android projects {initial-collapse-state="collapsed" collapsible="true"}

The Kotlin serialization library includes default [ProGuard rules](https://github.com/Kotlin/kotlinx.serialization/blob/master/rules/common.pro) that keep serializers for all serializable classes retained after shrinking.
These rules don't apply to classes with named companion objects.

To retain serializers for classes with named companion objects, add rules based on the [compatibility mode](https://r8.googlesource.com/r8/+/refs/heads/master/compatibility-faq.md) you use to your `proguard-rules.pro` file:

<tabs>
<tab id="compatibility" title="R8 compatibility mode">

```bash
# Serializer for classes with named companion objects are retrieved using getDeclaredClasses
# If you have any such classes, replace the examples below with your own
-keepattributes InnerClasses # Required for getDeclaredClasses

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions
com.example.myapplication.HasNamedCompanion2
{
static **$* *;
}
-keepnames class <1>$$serializer { # Using -keepnames is enough; class is kept when serializer() is kept
static <1>$$serializer INSTANCE;
}
```

</tab>

<tab id="full" title="R8 full mode">

```bash
# Serializer for classes with named companion objects are retrieved using getDeclaredClasses
# If you have any such classes, replace the examples below with your own
-keepattributes InnerClasses # Required for getDeclaredClasses

-if @kotlinx.serialization.Serializable class
com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions
com.example.myapplication.HasNamedCompanion2
{
static **$* *;
}
-keepnames class <1>$$serializer { # Using -keepnames is enough; class is kept when serializer() is kept
static <1>$$serializer INSTANCE;
}

# Keep both serializer and serializable classes to save the attribute InnerClasses
-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class
com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions
com.example.myapplication.HasNamedCompanion2
{
*;
}
```

</tab>
</tabs>

> You can exclude serializable classes that are never serialized at runtime by using custom ProGuard rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage).
>
{style="tip"}

## Serialize objects to JSON

In Kotlin, you can serialize objects to JSON using the `kotlinx.serialization` library.
Expand Down