Browser-like TLS profiles are not just about the user-agent header. Servers inspect the full handshake,
HTTP/2 behavior, and related transport traits. tls-client-node gives Node.js a cleaner wrapper around that
upstream capability while keeping the lifecycle explicit instead of hiding it behind singleton state.
`tls-client-node` is a source-available Node.js client for `bogdanfinn/tls-client`. It uses managed `tls-client-api` mode by default for predictable async concurrency, keeps lifecycle control explicit through `TLSClient` and `Session`, and can also run through direct shared-library loading when native mode is explicitly selected.
## Why tls-client-node
| Focus | What you get |
| --- | --- |
| Managed-first local runtime | Uses the `tls-client-api` sidecar process by default for more predictable concurrent async behavior. |
| Explicit lifecycle | `TLSClient` and `Session` keep ownership obvious, instead of hiding everything behind global init and destroy calls. |
| Upstream alignment | Custom TLS payloads and profile identifiers are kept close to Bogdan Finn's `tls-client` contract. |
| Migration practicality | Common `node-tls-client` aliases such as `ja3string`, `timeout`, `hostOverride`, and `randomTlsExtensionOrder` are supported. |
| Modern package surface | Published npm package with strict TypeScript types, named ESM imports, and CommonJS `require` support. |
## Highlights
- Clean named ESM imports and CommonJS `require` support.
- Default local runtime uses managed `tls-client-api`.
- Native mode is available through `runtimeMode: "native"`.
- Session-oriented API with explicit client and session control.
- Strict custom TLS handling with no silent fallback to stock client identifiers.
## Installation
```sh
npm install tls-client-node
# or
yarn add tls-client-node
# or
pnpm add tls-client-node
```
During `postinstall`, the package tries to download the matching upstream shared library for the current platform. If that step is skipped or fails, the required local asset is downloaded lazily on first startup.
Environment variables:
- `TLS_CLIENT_SKIP_DOWNLOAD=1` disables install-time downloads.
- `TLS_CLIENT_VERSION=1.14.0` pins the upstream asset version.
- `TLS_CLIENT_API_VERSION=1.14.0` is also recognized as an alias for `TLS_CLIENT_VERSION`.
- `TLS_CLIENT_RUNTIME_SLOTS=128` caps how many managed `tls-client-api` runtimes can run at once on a host (default `128`). The per-client `runtimeSlots` option overrides it. See [Runtime Modes](#runtime-modes).
## Imports
ESM named imports work directly:
```ts
import {
ClientIdentifier,
Emulation,
MultipartForm,
TLSClient,
createMultipartForm,
} from "tls-client-node";
const client = new TLSClient();
const session = client.session({
clientIdentifier: Emulation.chrome_136,
});
```
CommonJS is supported too:
```js
const { ClientIdentifier, Emulation, MultipartForm, TLSClient, createMultipartForm } = require("tls-client-node");
```
## Quick Start
```ts
import {
ClientIdentifier,
TLSClient,
} from "tls-client-node";
async function main() {
const client = new TLSClient();
const session = client.session({
clientIdentifier: ClientIdentifier.chrome_136,
});
const response = await session.get("https://tls.peet.ws/api/all");
console.log(response.status, await response.text());
await session.close();
await client.stop();
}
main().catch(console.error);
```
## High-Level Client
```ts
import { ClientIdentifier, TLSClient } from "tls-client-node";
const client = new TLSClient();
const session = client.session({
clientIdentifier: ClientIdentifier.chrome_136,
timeoutSeconds: 30,
headers: {
"user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
accept: "*/*",
"accept-language": "en-US,en;q=0.9",
"accept-encoding": "gzip, deflate, br",
},
});
const response = await session.get("https://tls.peet.ws/api/all");
console.log(response.status, response.usedProtocol);
await session.close();
await client.stop();
```
## One-Off Requests
```ts
import { ClientIdentifier, fetch } from "tls-client-node";
const response = await fetch("https://example.com", {
clientIdentifier: ClientIdentifier.chrome_136,
headers: {
accept: "text/html",
},
});
console.log(await response.text());
```
## Multipart Form Uploads
```ts
import { MultipartForm, TLSClient, createMultipartForm } from "tls-client-node";
const client = new TLSClient();
const form = createMultipartForm({
title: "example",
file: {
data: "hello world",
filename: "hello.txt",
contentType: "text/plain",
},
});
const builder = new MultipartForm()
.append("kind", "builder")
.appendJson("meta", { ok: true });
const response = await client.request("https://example.com/upload", {
method: "POST",
body: form,
});
console.log(response.status);
await client.request("https://example.com/upload-builder", {
method: "POST",
body: builder,
});
await client.stop();
```
## Redirect Ergonomics
```ts
import { TLSClient } from "tls-client-node";
const client = new TLSClient();
const session = client.session({
redirect: "follow",
});
await session.get("https://example.com/start", {
redirect: "manual",
});
await client.stop();
```
`redirect` is a higher-level alias for `followRedirects`.
- `redirect: "follow"` maps to `followRedirects: true`
- `redirect: "manual"` maps to `followRedirects: false`
- `redirect: true` and `redirect: false` are also accepted
## Runtime Modes
Default local mode is managed `tls-client-api`.
Use native mode only when you explicitly want direct shared-library loading:
```ts
import { TLSClient } from "tls-client-node";
const client = new TLSClient({
runtimeMode: "native",
});
```
If you already host `tls-client-api` yourself, use remote mode:
```ts
import { TLSClient } from "tls-client-node";
const client = new TLSClient({
baseUrl: "http://127.0.0.1:8080",
apiKey: "my-auth-key-1",
});
```
### Managed runtime slots
In managed mode each started `TLSClient` claims an isolated **runtime slot** — its own runtime directory, lock file, and `tls-client-api` child process — so multiple clients (and multiple OS processes) never collide on the same files or ports. A single runtime serves many concurrent sessions and requests, so you normally need **one slot per long-lived process**, not one per request.
Slots live under the runtime cache, keyed by upstream version:
| Platform | Location |
| --- | --- |
| Linux | `${XDG_CACHE_HOME:-~/.cache}/tls-client-node/runtime/
