Ktor Client JS

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.

Package Information

• Package Name: ktor-client-js
• Package Type: maven
• Language: Kotlin (compiles to JavaScript)
• Group ID: io.ktor
• Artifact ID: ktor-client-js
• Version: 3.2.0
• Installation: Add to build.gradle.kts:

  implementation("io.ktor:ktor-client-js:3.2.0")

Core Imports

import io.ktor.client.*
import io.ktor.client.engine.js.*

For convenience factory function:

import io.ktor.client.engine.js.JsClient

Basic Usage

import io.ktor.client.*
import io.ktor.client.engine.js.*
import io.ktor.client.request.*
import io.ktor.client.statement.*

// Create client with JS engine
val client = HttpClient(Js)
// or using convenience function
val client = JsClient()

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

// Configure with custom options
val client = HttpClient(Js) {
    engine {
        configureRequest {
            // Custom fetch options like credentials, cache, etc.
            credentials = "include"
            cache = "no-cache"
        }
    }
}

client.close()

Architecture

Ktor Client JS is built around several key components:

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

Capabilities

HTTP Engine

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

object Js : HttpClientEngineFactory<JsClientEngineConfig>

fun JsClient(): HttpClientEngineFactory<JsClientEngineConfig>

HTTP Engine

Engine Configuration

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

open class JsClientEngineConfig : HttpClientEngineConfig() {
    fun configureRequest(block: RequestInit.() -> Unit)
}

Engine Configuration

Request Configuration

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

fun HttpRequestBuilder.fetchOptions(block: RequestInit.() -> Unit)

Request Configuration

Error Handling

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

class JsError(val origin: dynamic) : Throwable

Error Handling

Fetch API Types

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

interface Request
interface Response  
interface Headers
interface RequestInit
external fun fetch(input: String, init: RequestInit? = definedExternally): Promise<Response>

Fetch API Types

Platform Support

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

Supported Capabilities

• HttpTimeoutCapability: Request timeout handling
• WebSocketCapability: WebSocket connections
• SSECapability: Server-Sent Events

Limitations

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