0
# Engine Configuration
1
2
Configuration system for customizing JavaScript client behavior, fetch options, and platform-specific settings. The configuration allows direct access to the underlying Fetch API options while maintaining Kotlin type safety.
3
4
## Capabilities
5
6
### JsClientEngineConfig
7
8
Configuration class for the JavaScript client engine that extends the base HTTP client engine configuration.
9
10
```kotlin { .api }
11
/**
12
* Configuration for the Js client.
13
*/
14
open class JsClientEngineConfig : HttpClientEngineConfig() {
15
/**
16
* Provides access to the underlying fetch options of the engine.
17
* It allows setting credentials, cache, mode, redirect, referrer, integrity, keepalive, signal, window.
18
*/
19
fun configureRequest(block: RequestInit.() -> Unit)
20
21
/**
22
* An Object which can contain additional configuration options that should get passed to node-fetch.
23
* @deprecated Use configureRequest instead
24
*/
25
@Deprecated("Use configureRequest instead", level = DeprecationLevel.WARNING)
26
var nodeOptions: dynamic
27
}
28
```
29
30
**Usage Examples:**
31
32
```kotlin
33
import io.ktor.client.*
34
import io.ktor.client.engine.js.*
35
36
// Configure fetch options
37
val client = HttpClient(Js) {
38
engine {
39
configureRequest {
40
// Set credentials for CORS requests
41
credentials = "include"
42
43
// Configure caching behavior
44
cache = "no-cache"
45
46
// Set request mode
47
mode = "cors"
48
49
// Configure redirect handling
50
redirect = "follow"
51
52
// Set referrer policy
53
referrer = "no-referrer"
54
55
// Enable keepalive for background requests
56
keepalive = true
57
}
58
}
59
}
60
```
61
62
### Configure Request Block
63
64
The `configureRequest` method provides access to all standard Fetch API options through a type-safe Kotlin DSL.
65
66
```kotlin { .api }
67
/**
68
* Configuration block for RequestInit options
69
* Provides access to all fetch API configuration options
70
* @param block Lambda with RequestInit receiver for configuration
71
*/
72
fun configureRequest(block: RequestInit.() -> Unit)
73
```
74
75
**Available RequestInit Properties:**
76
77
```kotlin { .api }
78
interface RequestInit {
79
var method: String?
80
var headers: dynamic
81
var body: dynamic
82
var mode: String? // "cors", "no-cors", "same-origin", "navigate"
83
var credentials: String? // "omit", "same-origin", "include"
84
var cache: String? // "default", "no-store", "reload", "no-cache", "force-cache", "only-if-cached"
85
var redirect: String? // "follow", "error", "manual"
86
var referrer: String? // URL string or "no-referrer", "client"
87
var referrerPolicy: String? // "no-referrer", "no-referrer-when-downgrade", etc.
88
var integrity: String? // Subresource integrity hash
89
var keepalive: Boolean? // Keep connection alive for background requests
90
var signal: AbortSignal? // AbortController signal for cancellation
91
var window: dynamic // Window object (browser only)
92
}
93
```
94
95
**Advanced Configuration Examples:**
96
97
```kotlin
98
import io.ktor.client.*
99
import io.ktor.client.engine.js.*
100
101
// CORS configuration
102
val corsClient = HttpClient(Js) {
103
engine {
104
configureRequest {
105
mode = "cors"
106
credentials = "include"
107
headers = js("""{
108
"Accept": "application/json",
109
"Content-Type": "application/json"
110
}""")
111
}
112
}
113
}
114
115
// Background request configuration
116
val backgroundClient = HttpClient(Js) {
117
engine {
118
configureRequest {
119
keepalive = true
120
cache = "no-cache"
121
}
122
}
123
}
124
125
// Request with abort signal
126
val controller = AbortController()
127
val abortableClient = HttpClient(Js) {
128
engine {
129
configureRequest {
130
signal = controller.signal
131
}
132
}
133
}
134
135
// Cancel the request later
136
// controller.abort()
137
```
138
139
### Legacy Node Options (Deprecated)
140
141
The `nodeOptions` property is deprecated but still available for backward compatibility.
142
143
```kotlin { .api }
144
/**
145
* @deprecated Use configureRequest instead
146
* An Object which can contain additional configuration options for node-fetch.
147
*/
148
@Deprecated("Use configureRequest instead", level = DeprecationLevel.WARNING)
149
var nodeOptions: dynamic
150
```
151
152
**Migration Example:**
153
154
```kotlin
155
// Old way (deprecated)
156
val client = HttpClient(Js) {
157
engine {
158
nodeOptions.agent = customAgent
159
}
160
}
161
162
// New way (recommended)
163
val client = HttpClient(Js) {
164
engine {
165
configureRequest {
166
// Use RequestInit properties instead
167
// Custom agents should be configured through proper fetch options
168
}
169
}
170
}
171
```
172
173
## Common Configuration Patterns
174
175
### Authentication with Credentials
176
177
```kotlin
178
val authClient = HttpClient(Js) {
179
engine {
180
configureRequest {
181
credentials = "include" // Send cookies and auth headers
182
}
183
}
184
}
185
```
186
187
### Cache Control
188
189
```kotlin
190
val noCacheClient = HttpClient(Js) {
191
engine {
192
configureRequest {
193
cache = "no-cache" // Always validate with server
194
// or cache = "no-store" // Never cache
195
// or cache = "reload" // Always fetch from server
196
}
197
}
198
}
199
```
200
201
### CORS Configuration
202
203
```kotlin
204
val corsClient = HttpClient(Js) {
205
engine {
206
configureRequest {
207
mode = "cors"
208
credentials = "same-origin"
209
referrerPolicy = "strict-origin-when-cross-origin"
210
}
211
}
212
}
213
```
214
215
### Request Integrity
216
217
```kotlin
218
val secureClient = HttpClient(Js) {
219
engine {
220
configureRequest {
221
integrity = "sha384-abc123..." // Subresource integrity hash
222
referrer = "no-referrer" // Don't send referrer header
223
}
224
}
225
}
226
```
227
228
## Platform Differences
229
230
- **Browser**: All RequestInit options are supported as per Fetch API specification
231
- **Node.js**: Some options like `window` are not applicable; agent configuration should be done through other means
232
- **WASM-JS**: Limited to basic fetch options supported by the WASM runtime