0
# Ktor Client Serialization (JavaScript)
1

2
A deprecated JavaScript platform-specific implementation for Ktor HTTP Client serialization plugin that integrates with Kotlinx Serialization for JSON serialization and deserialization. This package provides automatic registration of the KotlinxSerializer for JavaScript environments.
3

4
**⚠️ This package is deprecated since Ktor 2.0 in favor of the ContentNegotiation plugin.**
5

6
## Package Information
7

8
- **Package Name**: io.ktor:ktor-client-serialization-js
9
- **Package Type**: maven
10
- **Language**: Kotlin (JavaScript target)
11
- **Installation**: 
12
  ```kotlin
13
  implementation("io.ktor:ktor-client-serialization:3.2.0")
14
  ```
15

16
## Core Imports
17

18
```kotlin
19
import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
20
import io.ktor.client.plugins.json.*
21
import kotlinx.serialization.json.Json
22
```
23

24
## Basic Usage
25

26
```kotlin
27
import io.ktor.client.*
28
import io.ktor.client.plugins.json.*
29
import io.ktor.client.plugins.kotlinx.serializer.*
30
import kotlinx.serialization.*
31
import kotlinx.serialization.json.*
32

33
// The serializer is automatically registered on JavaScript platform
34
// through the SerializerInitializer
35

36
// Create HTTP client with JSON plugin (deprecated)
37
@Suppress("DEPRECATION_ERROR")
38
val client = HttpClient {
39
    install(JsonPlugin) {
40
        serializer = KotlinxSerializer()
41
    }
42
}
43

44
// Or use custom Json configuration
45
@Suppress("DEPRECATION_ERROR")
46
val customClient = HttpClient {
47
    install(JsonPlugin) {
48
        serializer = KotlinxSerializer(Json {
49
            isLenient = true
50
            ignoreUnknownKeys = true
51
        })
52
    }
53
}
54
```
55

56
## Architecture
57

58
The package consists of three main components:
59

60
- **KotlinxSerializer**: The core serializer implementation that handles JSON serialization/deserialization using Kotlinx Serialization
61
- **Platform Initializers**: JavaScript and WebAssembly-specific initializers that automatically register the serializer
62
- **Type System Integration**: Automatic serializer detection for various Kotlin data types including collections, maps, and custom serializable classes
63

64
## Capabilities
65

66
### JSON Serialization
67

68
Core JSON serialization functionality using Kotlinx Serialization for type-safe conversion between Kotlin objects and JSON.
69

70
```kotlin { .api }
71
@Deprecated("Please use ContentNegotiation plugin and its converters")
72
class KotlinxSerializer(
73
    private val json: Json = DefaultJson
74
) : JsonSerializer {
75
    
76
    /**
77
     * Convert data object to OutgoingContent with specified content type
78
     */
79
    fun write(data: Any, contentType: ContentType): OutgoingContent
80
    
81
    /**
82
     * Convert data object to OutgoingContent with default JSON content type
83
     */
84
    fun write(data: Any): OutgoingContent
85
    
86
    /**
87
     * Read content from response using type information
88
     */
89
    fun read(type: TypeInfo, body: Input): Any
90
    
91
    companion object {
92
        /**
93
         * Default Json configuration for KotlinxSerializer
94
         */
95
        val DefaultJson: Json
96
    }
97
}
98
```
99

100
**Usage Examples:**
101

102
```kotlin
103
@Serializable
104
data class User(val name: String, val age: Int)
105

106
// Serialization is handled automatically by the HTTP client
107
val response = client.post<User>("https://api.example.com/users") {
108
    body = User("Alice", 30)
109
}
110
```
111

112
### Automatic Platform Registration
113

114
JavaScript and WebAssembly platform-specific automatic serializer registration.
115

116
```kotlin { .api }
117
/**
118
 * Platform initializer that automatically registers KotlinxSerializer
119
 * Available on both JavaScript and WebAssembly platforms with identical implementation
120
 */
121
@InternalAPI
122
object SerializerInitializer {
123
    /**
124
     * Eager initialization property that triggers serializer registration
125
     */
126
    @EagerInitialization
127
    val initializer: SerializerInitializer
128
}
129
```
130

131
The initializer automatically adds `KotlinxSerializer()` to the platform-specific serializers store during module initialization. Both JavaScript and WebAssembly platforms use identical implementations.
132

133
### Supported Data Types
134

135
The serializer supports various Kotlin data types with automatic serializer detection:
136

137
```kotlin { .api }
138
// Supported types (handled automatically):
139
// - JsonElement: Direct serialization
140
// - List<*>: ListSerializer with element type detection
141
// - Array<*>: Array serialization with fallback to String serializer
142
// - Set<*>: SetSerializer with element type detection  
143
// - Map<*, *>: MapSerializer with key/value type detection
144
// - Custom @Serializable classes: Via reflection and SerializersModule
145
// - Nullable types: Automatic nullable serializer wrapping
146
```
147

148
**Error Handling:**
149

150
- Throws error for collections with mixed element types
151
- Provides descriptive error messages with serializer information
152
- Falls back to String serializer for unknown/empty collections
153

154
### Default JSON Configuration
155

156
Pre-configured JSON settings optimized for HTTP client usage:
157

158
```kotlin { .api }
159
/**
160
 * Default Json configuration for KotlinxSerializer
161
 */
162
val DefaultJson: Json = Json {
163
    isLenient = false
164
    ignoreUnknownKeys = false
165
    allowSpecialFloatingPointValues = true
166
    useArrayPolymorphism = false
167
}
168
```
169

170
## Migration
171

172
This package is deprecated in favor of the ContentNegotiation plugin. To migrate:
173

174
```kotlin
175
// Old (deprecated)
176
@Suppress("DEPRECATION_ERROR")
177
val client = HttpClient {
178
    install(JsonPlugin) {
179
        serializer = KotlinxSerializer()
180
    }
181
}
182

183
// New (recommended)
184
val client = HttpClient {
185
    install(ContentNegotiation) {
186
        json(Json {
187
            isLenient = true
188
            ignoreUnknownKeys = true
189
        })
190
    }
191
}
192
```
193

194
For detailed migration instructions, see: https://ktor.io/docs/migration-to-20x.html#serialization-client
195

196
## Platform Availability
197

198
- **Primary Target**: JavaScript (browser and Node.js environments)
199
- **Secondary Target**: WebAssembly with JavaScript interop
200
- **Registration**: Automatic via `@EagerInitialization` during module loading