Registry / http-networking / tls-client-node

tls-client-node

library0.1.13jsnpmunverified

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.

http-networking auth-security

npm install tls-client-node

github ↗package ↗

INSTALL

IMPORT

SIG · TLS-CLIENT-NODE

tls-client-node

http-networkingjavascriptv0.1.13

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TLSClient

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

✗ import TLSClient from 'tls-client-node'

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

Session

✓ import { Session } from 'tls-client-node'

✗ const { Session } = require('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

✓ import type { RequestPayload } from 'tls-client-node'

✗ import { RequestPayload } from 'tls-client-node'

RequestPayload is a TypeScript type, not a runtime value. Use 'import type' for type-only imports.

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);

Debug

Known issues

gotchaMust 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.

affects: >=0.1.0

gotchaUsing 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.

affects: >=0.1.0

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

fix

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

affects: >=0.1.12

breakingv0.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.

affects: >=0.1.0

gotchaEmulation 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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/.

TypeError: client.session is not a function

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: Managed runtime process exited unexpectedly. Please check tls-client-api logs.

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: connect ECONNREFUSED ::1:443

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.

Upgrade

Version history

0.1.13latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fatihkabakk/tls-client-node ↗

packagehttps://www.npmjs.com/package/tls-client-node ↗