0
# Ktor Client JS
1

2
Ktor Client JS is a JavaScript/TypeScript HTTP client implementation that provides asynchronous HTTP client functionality specifically tailored for JavaScript environments. Part of the Ktor framework, this module enables developers to make HTTP requests from Kotlin/JS applications using the native Fetch API in browsers and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: ktor-client-js
7
- **Package Type**: maven
8
- **Language**: Kotlin (compiles to JavaScript)
9
- **Group ID**: io.ktor
10
- **Artifact ID**: ktor-client-js
11
- **Version**: 3.2.0
12
- **Installation**: Add to `build.gradle.kts`:
13
  ```kotlin
14
  implementation("io.ktor:ktor-client-js:3.2.0")
15
  ```
16

17
## Core Imports
18

19
```kotlin
20
import io.ktor.client.*
21
import io.ktor.client.engine.js.*
22
```
23

24
For convenience factory function:
25
```kotlin
26
import io.ktor.client.engine.js.JsClient
27
```
28

29
## Basic Usage
30

31
```kotlin
32
import io.ktor.client.*
33
import io.ktor.client.engine.js.*
34
import io.ktor.client.request.*
35
import io.ktor.client.statement.*
36

37
// Create client with JS engine
38
val client = HttpClient(Js)
39
// or using convenience function
40
val client = JsClient()
41

42
// Make HTTP request
43
val response: HttpResponse = client.get("https://api.example.com/data")
44
val content: String = response.bodyAsText()
45

46
// Configure with custom options
47
val client = HttpClient(Js) {
48
    engine {
49
        configureRequest {
50
            // Custom fetch options like credentials, cache, etc.
51
            credentials = "include"
52
            cache = "no-cache"
53
        }
54
    }
55
}
56

57
client.close()
58
```
59

60
## Architecture
61

62
Ktor Client JS is built around several key components:
63

64
- **JS Engine**: The core `Js` engine factory that creates HTTP clients using the Fetch API
65
- **Configuration System**: `JsClientEngineConfig` for customizing engine behavior and fetch options
66
- **Fetch API Integration**: Direct access to browser and Node.js fetch APIs with full TypeScript definitions
67
- **Error Handling**: Specialized `JsError` class for wrapping JavaScript runtime errors
68
- **Cross-platform Support**: Works in both browser and Node.js environments with automatic environment detection
69

70
## Capabilities
71

72
### HTTP Engine
73

74
Core JavaScript HTTP client engine using the Fetch API for executing requests with full coroutine support.
75

76
```kotlin { .api }
77
object Js : HttpClientEngineFactory<JsClientEngineConfig>
78

79
fun JsClient(): HttpClientEngineFactory<JsClientEngineConfig>
80
```
81

82
[HTTP Engine](./http-engine.md)
83

84
### Engine Configuration  
85

86
Configuration system for customizing JavaScript client behavior, fetch options, and platform-specific settings.
87

88
```kotlin { .api }
89
open class JsClientEngineConfig : HttpClientEngineConfig() {
90
    fun configureRequest(block: RequestInit.() -> Unit)
91
}
92
```
93

94
[Engine Configuration](./engine-configuration.md)
95

96
### Request Configuration
97

98
Extensions for configuring individual HTTP requests with custom fetch options and JavaScript-specific parameters.
99

100
```kotlin { .api }
101
fun HttpRequestBuilder.fetchOptions(block: RequestInit.() -> Unit)
102
```
103

104
[Request Configuration](./request-configuration.md)
105

106
### Error Handling
107

108
JavaScript-specific error handling with wrapped native JavaScript errors for debugging and error reporting.
109

110
```kotlin { .api }
111
class JsError(val origin: dynamic) : Throwable
112
```
113

114
[Error Handling](./error-handling.md)
115

116
### Fetch API Types
117

118
Complete TypeScript-compatible type definitions for the Fetch API, DOM interfaces, and JavaScript runtime types.
119

120
```kotlin { .api }
121
interface Request
122
interface Response  
123
interface Headers
124
interface RequestInit
125
external fun fetch(input: String, init: RequestInit? = definedExternally): Promise<Response>
126
```
127

128
[Fetch API Types](./fetch-api-types.md)
129

130
## Platform Support
131

132
- **Browser**: Full support using native Fetch API
133
- **Node.js**: Support using dynamic imports for 'ws' and node-fetch libraries  
134
- **WebAssembly**: Partial support through WASM-JS target
135

136
## Supported Capabilities
137

138
- **HttpTimeoutCapability**: Request timeout handling
139
- **WebSocketCapability**: WebSocket connections  
140
- **SSECapability**: Server-Sent Events
141

142
## Limitations
143

144
- **Proxy Support**: Not supported - proxy configuration will throw exceptions
145
- **Custom Certificates**: Limited certificate configuration compared to JVM clients
146
- **HTTP/2**: Depends on browser/Node.js support for HTTP/2 over Fetch API