Skip to content

Commit 32c62a1

Browse files
Enhance README with additional details and tips
Expanded README with detailed explanations on usage and features.
1 parent fc3e6ec commit 32c62a1

1 file changed

Lines changed: 28 additions & 4 deletions

File tree

README.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,32 @@
11
# node-wreq
22

3-
`node-wreq` is a Node HTTP client with a Rust transport underneath backed by [`wreq`](https://github.com/0x676e67/wreq).
4-
5-
This package helps if you need low-level control over the network layer — TLS configuration, transport fingerprinting, browser impersonation, or fine-grained HTTP/WebSocket behavior that standard Node.js clients don't expose.
3+
[![NPM Version](https://img.shields.io/npm/v/node-wreq)](https://npmjs.com/package/node-wreq)
4+
![ESM](https://img.shields.io/badge/ESM-supported-brightgreen)
5+
![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows-lightgrey)
6+
7+
`node-wreq` is a thin Node.js wrapper around 0x676e67's [`wreq`](https://github.com/0x676e67/wreq)
8+
a Rust HTTP client exposing its full power to JavaScript.
9+
10+
Use it when you need low-level control over the network layer: TLS configuration,
11+
transport fingerprinting, browser impersonation, or fine-grained HTTP/WebSocket
12+
behavior that standard Node.js clients simply don't expose.
13+
14+
> [!TIP]
15+
> ### why does this exist?
16+
>
17+
> Node.js ships with a built-in `https` module, and the ecosystem offers popular clients like `axios`, `got`, and `node-fetch` — but all of them are built on top of OpenSSL via Node's `tls` module, which exposes **no control over low-level TLS handshake parameters**. This makes it fundamentally impossible to emulate real browser network behavior from pure JavaScript.
18+
>
19+
> - **HTTP/1 over TLS**
20+
>
21+
> Node.js HTTP clients normalize headers to lowercase internally, which is compliant with HTTP/2 semantics but breaks compatibility with some **WAFs** that enforce case-sensitive header validation on **HTTP/1** requests. This wrapper preserves header case exactly as specified, preventing requests from being silently rejected.
22+
>
23+
> - **HTTP/2 over TLS**
24+
>
25+
> Fingerprints like **JA3**, **JA4**, and **Akamai HTTP/2** are derived from the specifics of the TLS handshake and HTTP/2 SETTINGS frames — cipher suite ordering, TLS extensions, ALPN values, HPACK header compression parameters, and more. Node.js exposes none of these through its `tls` or `http2` APIs. You simply cannot spoof them from JS land, no matter the library. This package solves that at the native layer, giving you fine-grained control over TLS and HTTP/2 extensions to precisely match real browser behavior.
26+
>
27+
> - **Device Emulation**
28+
>
29+
> Because TLS and HTTP/2 fingerprints evolve slowly relative to browser release cycles, a single fingerprint profile often covers many browser versions. **100+ pre-built browser device profiles** are bundled, so you don't have to figure out the right combination of settings yourself.
630
731
## install
832

@@ -24,7 +48,7 @@ npm install node-wreq
2448
#### 🔌   **[websockets](#websockets)**
2549
#### 🧪   **[networking / transport knobs](#networking)** — TLS, HTTP/1, HTTP/2 options; header ordering.
2650

27-
## ⚡ <a id="quick-start"></a>quick start   ·   [](#contents)
51+
## ⚡ <a id="quick-start"></a>quick start
2852

2953
```ts
3054
import { fetch } from 'node-wreq';

0 commit comments

Comments
 (0)