0
# HTTP Engine
1

2
The core JavaScript HTTP client engine that provides asynchronous HTTP client functionality using the Fetch API. This engine works seamlessly across browser and Node.js environments with automatic platform detection.
3

4
## Capabilities
5

6
### Js Engine Object
7

8
The main JavaScript client engine factory that creates HTTP clients.
9

10
```kotlin { .api }
11
/**
12
 * A JavaScript client engine that uses the fetch API to execute requests.
13
 * 
14
 * To create the client with this engine, pass it to the HttpClient constructor:
15
 * ```kotlin
16
 * val client = HttpClient(Js)
17
 * ```
18
 */
19
object Js : HttpClientEngineFactory<JsClientEngineConfig> {
20
    override fun create(block: JsClientEngineConfig.() -> Unit): HttpClientEngine
21
}
22
```
23

24
**Usage Examples:**
25

26
```kotlin
27
import io.ktor.client.*
28
import io.ktor.client.engine.js.*
29

30
// Basic client creation
31
val client = HttpClient(Js)
32

33
// With configuration
34
val client = HttpClient(Js) {
35
    engine {
36
        configureRequest {
37
            credentials = "include"
38
        }
39
    }
40
}
41
```
42

43
### JsClient Factory Function
44

45
Convenience function to get the Js engine singleton.
46

47
```kotlin { .api }
48
/**
49
 * Creates a Js client engine.
50
 * @return HttpClientEngineFactory for the Js engine
51
 */
52
@JsName("JsClient")
53
fun JsClient(): HttpClientEngineFactory<JsClientEngineConfig>
54
```
55

56
**Usage Examples:**
57

58
```kotlin
59
import io.ktor.client.engine.js.JsClient
60

61
// Using convenience function
62
val client = JsClient()
63

64
// Equivalent to HttpClient(Js) but more concise
65
val engine = JsClient()
66
val client = HttpClient(engine)
67
```
68

69
### HttpClient Constructor
70

71
Platform-specific HttpClient constructor for JavaScript environments.
72

73
```kotlin { .api }
74
/**
75
 * Constructs an asynchronous HttpClient for JavaScript platform.
76
 * @param block Configuration block for the client
77
 * @return Configured HttpClient instance
78
 */
79
fun HttpClient(block: HttpClientConfig<*>.() -> Unit = {}): HttpClient
80
```
81

82
**Usage Examples:**
83

84
```kotlin
85
import io.ktor.client.*
86
import io.ktor.client.plugins.contentnegotiation.*
87
import io.ktor.serialization.kotlinx.json.*
88

89
// Default client for JS platform
90
val client = HttpClient()
91

92
// With plugins and configuration
93
val client = HttpClient {
94
    install(ContentNegotiation) {
95
        json()
96
    }
97
    expectSuccess = true
98
}
99
```
100

101
## Engine Capabilities
102

103
The Js engine supports the following Ktor capabilities:
104

105
- **HttpTimeoutCapability**: Request timeout handling with automatic cancellation
106
- **WebSocketCapability**: WebSocket connections using native browser WebSocket API or 'ws' library in Node.js
107
- **SSECapability**: Server-Sent Events support for real-time data streaming
108

109
## Platform Detection
110

111
The engine automatically detects the runtime environment:
112

113
- **Browser Environment**: Uses native `fetch()` API and `WebSocket` constructor
114
- **Node.js Environment**: Dynamically imports `node-fetch` and `ws` libraries
115
- **WASM-JS Environment**: Uses WASM-compatible fetch implementation
116

117
## Error Handling
118

119
All JavaScript runtime errors are wrapped in `JsError` for consistent error handling across platforms:
120

121
```kotlin
122
try {
123
    val response = client.get("https://api.example.com")
124
} catch (error: JsError) {
125
    println("JavaScript error: ${error.origin}")
126
    // error.origin contains the original JavaScript error object
127
}
128
```
129

130
## Limitations
131

132
- **Proxy Configuration**: Not supported - will throw exceptions if proxy is configured
133
- **Custom SSL Certificates**: Limited compared to JVM implementations
134
- **Connection Pooling**: Relies on browser/Node.js connection management