Skip to content

Repository files navigation

node-tls-client

A Node.js HTTP client that looks like a real browser at the TLS and HTTP/2 level.

NPM version NPM downloads

NPM Banner

Documentation

Changing the User-Agent isn't enough to look like a browser: servers can recognise the client from its TLS handshake and HTTP/2 settings (TLS fingerprinting: JA3, JA4, Akamai). node-tls-client sends requests through bogdanfinn/tls-client, which reproduces the handshake of real browsers, behind a fetch-like API.

Installation

npm install node-tls-client

Requires Node.js 20 or newer. The native library is downloaded on first use; see Installation for platforms (Alpine/musl isn't supported yet) and offline installs.

Quick start

import {
  initTLS,
  destroyTLS,
  Session,
  ClientIdentifier,
} from "node-tls-client";

await initTLS();

const session = new Session({
  clientIdentifier: ClientIdentifier.chrome_150,
  headers: {
    "user-agent":
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
  },
  timeout: 10_000,
});

const res = await session.get("https://tls.peet.ws/api/all");
console.log(res.status, (await res.json()).tls.ja4);

await session.close();
await destroyTLS();

The profile sets the handshake, not the headers: always send a user-agent that matches it. More in the Quick start.

Guides

Upgrading from 2.1? Check the changelog: request headers now merge over session headers, and the default profile is chrome_150. 2.2 uses a fraction of 2.1's CPU and memory, and the node-tls-client binary runs requests without holding a thread; see Performance.

Runnable versions of every example are in examples/.

Acknowledgements

This library is based on bogdanfinn's tls client in golang. A big thanks to him.

Used by

Contributors

Languages