tls-client-node

0.1.13 verified Sat May 09 auth: no javascript

Node.js wrapper for bogdanfinn/tls-client providing browser-like TLS fingerprinting via JA3, HTTP/2, and HTTP/3. Version 0.1.13 is current, with frequent releases. Uses a managed sidecar process (tls-client-api) by default for predictable async concurrency, with an optional native shared-library mode. Ships strict TypeScript types, supports ESM and CJS, and keeps lifecycle explicit through TLSClient and Session objects. Differentiates from node-tls-client by avoiding singleton state and aligning payloads closely with the upstream Go library. Requires Node.js >=18.17 and downloads platform-specific binaries during postinstall.

Common errors

error Error: Failed to download tls-client library. Please check your network connection or set TLS_CLIENT_SKIP_DOWNLOAD=1. ↓

cause Postinstall script failed to download the platform-specific shared library binary.

fix

Set TLS_CLIENT_SKIP_DOWNLOAD=1 before install, then manually download the library and place it in node_modules/tls-client-node/bin/.

error TypeError: client.session is not a function ↓

cause Importing TLSClient incorrectly (default import instead of named import) results in undefined.

fix

Use import { TLSClient } from 'tls-client-node' instead of import TLSClient from 'tls-client-node'.

error Error: Managed runtime process exited unexpectedly. Please check tls-client-api logs. ↓

cause The managed sidecar process crashed, possibly due to a version mismatch or corrupted binary.

fix

Upgrade to latest version, delete node_modules/tls-client-node/bin and reinstall, or switch to runtimeMode: 'native'.

error Error: connect ECONNREFUSED ::1:443 ↓

cause The library attempted to connect via IPv6 but the target server or network does not support it.

fix

Set the 'family' option to 4 in the session configuration to force IPv4.

Warnings

gotcha Must call close() on both Session and TLSClient to release resources; forgetting causes resource leaks and hanging processes. ↓

fix Use try/finally or async dispose patterns to ensure session.close() and client.close() are called.

gotcha Using native runtimeMode without the matching shared library download will throw a runtime error. The postinstall script may fail on some platforms. ↓

fix Either rely on default managed mode or ensure TLS_CLIENT_VERSION is set to a supported version and the binary is present.

deprecated The 'timeout' option is deprecated in favor of 'requestTimeout' and 'connectTimeout'. ↓

fix Replace 'timeout' with 'requestTimeout' for request-level timeout or 'connectTimeout' for connection timeout.

breaking v0.1.0 changed the return type of session.get/post from string to an object with status, headers, and body properties. ↓

fix Access response.body instead of using the raw response value.

gotcha Emulation presets only affect TLS parameters; custom HTTP headers like User-Agent must still be set manually. ↓

fix Always set User-Agent and other headers matching the emulated browser in the request options.

Install

npm install tls-client-node

yarn add tls-client-node

pnpm add tls-client-node

Imports

TLSClient

wrong

import TLSClient from 'tls-client-node'

correct

import { TLSClient } from 'tls-client-node'

Named export, not default. Works with both ESM and CJS (require).

Session
wrong
```
const { Session } = require('tls-client-node')
```
correct
```
import { Session } from 'tls-client-node'
```
This works, but Session is typically obtained via TLSClient.session(), not constructed directly.
ClientIdentifier
```
import { ClientIdentifier } from 'tls-client-node'
```
Type for custom TLS client identifiers; used when not using Emulation presets.
Emulation
```
import { Emulation } from 'tls-client-node'
```
Enum of browser emulation presets (e.g., Emulation.chrome_136).
RequestPayload
wrong
```
import { RequestPayload } from 'tls-client-node'
```
correct
```
import type { RequestPayload } from 'tls-client-node'
```
RequestPayload is a TypeScript type, not a runtime value. Use 'import type' for type-only imports.

Quickstart

Creates a TLSClient, opens a session with Chrome 136 emulation, makes a GET request, and properly closes session and client.

import { TLSClient, Emulation } from 'tls-client-node';

async function main() {
  const client = new TLSClient();
  const session = client.session({
    clientIdentifier: Emulation.chrome_136,
  });

  try {
    const response = await session.get('https://httpbin.org/get', {
      headers: { 'User-Agent': 'Mozilla/5.0 ... Chrome/136.0.0.0' },
    });
    console.log('Status:', response.status);
    console.log('Body:', response.body);
  } finally {
    await session.close();
    await client.close();
  }
}

main().catch(console.error);