{"id":28395,"library":"tls-client-node","title":"tls-client-node","description":"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.","status":"active","version":"0.1.13","language":"javascript","source_language":"en","source_url":"https://github.com/fatihkabakk/tls-client-node","tags":["javascript","tls-client","tls-client-node","ja3","ja3-fingerprint","tls-fingerprint","clienthello","http-client","http2","typescript"],"install":[{"cmd":"npm install tls-client-node","lang":"bash","label":"npm"},{"cmd":"yarn add tls-client-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add tls-client-node","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Named export, not default. Works with both ESM and CJS (require).","wrong":"import TLSClient from 'tls-client-node'","symbol":"TLSClient","correct":"import { TLSClient } from 'tls-client-node'"},{"note":"This works, but Session is typically obtained via TLSClient.session(), not constructed directly.","wrong":"const { Session } = require('tls-client-node')","symbol":"Session","correct":"import { Session } from 'tls-client-node'"},{"note":"Type for custom TLS client identifiers; used when not using Emulation presets.","wrong":null,"symbol":"ClientIdentifier","correct":"import { ClientIdentifier } from 'tls-client-node'"},{"note":"Enum of browser emulation presets (e.g., Emulation.chrome_136).","wrong":null,"symbol":"Emulation","correct":"import { Emulation } from 'tls-client-node'"},{"note":"RequestPayload is a TypeScript type, not a runtime value. Use 'import type' for type-only imports.","wrong":"import { RequestPayload } from 'tls-client-node'","symbol":"RequestPayload","correct":"import type { RequestPayload } from 'tls-client-node'"}],"quickstart":{"code":"import { TLSClient, Emulation } from 'tls-client-node';\n\nasync function main() {\n  const client = new TLSClient();\n  const session = client.session({\n    clientIdentifier: Emulation.chrome_136,\n  });\n\n  try {\n    const response = await session.get('https://httpbin.org/get', {\n      headers: { 'User-Agent': 'Mozilla/5.0 ... Chrome/136.0.0.0' },\n    });\n    console.log('Status:', response.status);\n    console.log('Body:', response.body);\n  } finally {\n    await session.close();\n    await client.close();\n  }\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Creates a TLSClient, opens a session with Chrome 136 emulation, makes a GET request, and properly closes session and client."},"warnings":[{"fix":"Use try/finally or async dispose patterns to ensure session.close() and client.close() are called.","message":"Must call close() on both Session and TLSClient to release resources; forgetting causes resource leaks and hanging processes.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Either rely on default managed mode or ensure TLS_CLIENT_VERSION is set to a supported version and the binary is present.","message":"Using native runtimeMode without the matching shared library download will throw a runtime error. The postinstall script may fail on some platforms.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Replace 'timeout' with 'requestTimeout' for request-level timeout or 'connectTimeout' for connection timeout.","message":"The 'timeout' option is deprecated in favor of 'requestTimeout' and 'connectTimeout'.","severity":"deprecated","affected_versions":">=0.1.12"},{"fix":"Access response.body instead of using the raw response value.","message":"v0.1.0 changed the return type of session.get/post from string to an object with status, headers, and body properties.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always set User-Agent and other headers matching the emulated browser in the request options.","message":"Emulation presets only affect TLS parameters; custom HTTP headers like User-Agent must still be set manually.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Set TLS_CLIENT_SKIP_DOWNLOAD=1 before install, then manually download the library and place it in node_modules/tls-client-node/bin/.","cause":"Postinstall script failed to download the platform-specific shared library binary.","error":"Error: Failed to download tls-client library. Please check your network connection or set TLS_CLIENT_SKIP_DOWNLOAD=1."},{"fix":"Use import { TLSClient } from 'tls-client-node' instead of import TLSClient from 'tls-client-node'.","cause":"Importing TLSClient incorrectly (default import instead of named import) results in undefined.","error":"TypeError: client.session is not a function"},{"fix":"Upgrade to latest version, delete node_modules/tls-client-node/bin and reinstall, or switch to runtimeMode: 'native'.","cause":"The managed sidecar process crashed, possibly due to a version mismatch or corrupted binary.","error":"Error: Managed runtime process exited unexpectedly. Please check tls-client-api logs."},{"fix":"Set the 'family' option to 4 in the session configuration to force IPv4.","cause":"The library attempted to connect via IPv6 but the target server or network does not support it.","error":"Error: connect ECONNREFUSED ::1:443"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}