Registry / http-networking / socks5-client

socks5-client

JSON →
library1.2.8jsnpmunverified

This package provides a low-level, unopinionated SOCKS v5 client socket implementation specifically designed for Node.js. It allows developers to proxy raw TCP connections through a SOCKSv5 server by wrapping a standard `net.Socket` and performing the SOCKSv5 handshake. First published in 2012 and last updated seven years ago (version 1.2.8), its release cadence is effectively abandoned, although the package remains available and functional for its specific niche. It serves as a foundational component for other packages like `socks5-http-client` and `socks5-https-client`. Unlike more modern SOCKS client libraries, `socks5-client` focuses solely on the SOCKSv5 protocol, operates synchronously, and does not include modern JavaScript features like Promises or built-in TypeScript definitions. Its key differentiator is its minimalist approach, providing direct control over the underlying socket stream for advanced use cases.

npm install socks5-client
INSTALL
IMPORT
SIG · SOCKS5-CLIENT
S
socks5-client
http-networkingjavascriptv1.2.8
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

SocksClient
const SocksClient = require('socks5-client');
import { SocksClient } from 'socks5-client';
This package is CommonJS-only. Direct ESM `import` statements are not supported and will result in runtime errors. Use dynamic `import()` or transpilation for ESM compatibility.
SocksClient (instantiation)
const client = new SocksClient(options);
const client = SocksClient(options);
The primary export is a constructor function (class-like), requiring `new` for instantiation. Calling it directly as a function will likely lead to errors related to `this` context.
SocksClient methods
client.connect(port, host, callback);
client.connectAsync(port, host, callback);
Methods generally use a callback-style API. There are no built-in Promise-based equivalents; manual promisification is required for modern async/await patterns.

This example demonstrates how to establish a SOCKSv5 proxied TCP connection to `example.com` on port 80. It first connects a raw `net.Socket` to the SOCKS5 proxy, then uses `socks5-client` to perform the SOCKS5 handshake and obtain a `destinationSocket` which is then used to send an HTTP GET request to the target host.

const net = require('net'); const SocksClient = require('socks5-client'); const PROXY_HOST = process.env.SOCKS5_PROXY_HOST || '127.0.0.1'; const PROXY_PORT = parseInt(process.env.SOCKS5_PROXY_PORT || '1080', 10); const TARGET_HOST = 'example.com'; const TARGET_PORT = 80; // Create a raw TCP socket to connect to the SOCKS5 proxy const proxySocket = net.connect(PROXY_PORT, PROXY_HOST, () => { console.log(`Connected to SOCKS5 proxy at ${PROXY_HOST}:${PROXY_PORT}`); // Instantiate SocksClient with the proxy connection const socksClient = new SocksClient(); // Initiate the SOCKS5 handshake to connect to the target host socksClient.connect( TARGET_PORT, TARGET_HOST, // Optional: add 'socksUsername', 'socksPassword' to options for auth // { socksUsername: 'user', socksPassword: 'pass' }, proxySocket, // Pass the connected proxySocket (err, destinationSocket) => { if (err) { console.error('SOCKS5 connection failed:', err.message); proxySocket.end(); return; } console.log(`Successfully connected to ${TARGET_HOST}:${TARGET_PORT} via SOCKS5 proxy.`); // Now destinationSocket is the proxied socket, ready for application data const request = [ 'GET / HTTP/1.1', `Host: ${TARGET_HOST}`, 'Connection: close', '', '' ].join('\r\n'); destinationSocket.write(request); destinationSocket.on('data', (data) => { console.log('Received data from target:', data.toString().substring(0, 200) + '...'); }); destinationSocket.on('end', () => { console.log('Target connection ended.'); proxySocket.end(); }); destinationSocket.on('error', (data) => { console.error('Target socket error:', data.message); proxySocket.end(); }); } ); }); proxySocket.on('error', (err) => { console.error('Proxy socket error:', err.message); });
Debug
Known issues
gotchaThis package is CommonJS (CJS) only. Attempting to use `import` statements directly in an ESM context will lead to runtime errors (e.g., `TypeError: (0 , _socks5Client.default) is not a constructor`).
fix
For ESM projects, use `const SocksClient = require('socks5-client');` or consider a dynamic import: `const SocksClient = (await import('socks5-client')).default;`. For TypeScript, ensure `esModuleInterop` is enabled and use `import SocksClient = require('socks5-client');` or `import * as SocksClient from 'socks5-client';`.
affects: >=1.0.0
gotchaThe package has not been updated in over seven years (since version 1.2.8). This means it may not be actively maintained, could have unpatched bugs or security vulnerabilities, and might exhibit compatibility issues with newer Node.js versions or modern JavaScript features. For instance, packages depending on `socks5-client` have reported issues with Node.js versions above 14.17.0.
fix
Evaluate alternatives like the `socks` package (npm: `socks`), which is actively maintained, supports Promises, TypeScript, and multiple SOCKS versions. If forced to use `socks5-client`, thorough testing across target Node.js versions is crucial, and be prepared to patch the code or implement workarounds for modern environments.
affects: >=1.0.0
gotchaThe `socks5-client` library only implements basic SOCKSv5 CONNECT command functionality and 'no-authentication' or simple username/password authentication (if implemented in the original fork). It does not natively support SOCKS4/4a, UDP ASSOCIATE, or more advanced authentication methods like GSS-API.
fix
If your use case requires SOCKS4, UDP, or complex authentication, `socks5-client` is not suitable. Consider libraries like `socks` (npm: `socks`) that offer broader protocol and feature support. Validate that your SOCKSv5 proxy supports the authentication methods provided by `socks5-client`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: (0 , _socks5Client.default) is not a constructor
Attempting to import a CommonJS-only package (`socks5-client`) using ES Module syntax (`import { SocksClient } from 'socks5-client';`) in a Node.js ESM project.
fix
Change your import statement to `const SocksClient = require('socks5-client');`. If using TypeScript, ensure `esModuleInterop` is true in `tsconfig.json` and use `import SocksClient = require('socks5-client');` or `import * as SocksClient from 'socks5-client';`.
Error: connect ECONNREFUSED <proxy_host>:<proxy_port>
The SOCKS5 proxy server is not running, is inaccessible, or the provided `proxy_host` or `proxy_port` is incorrect.
fix
Verify that your SOCKS5 proxy server is operational and reachable from the machine running your Node.js application. Double-check the `PROXY_HOST` and `PROXY_PORT` configurations. Firewall rules might also be blocking the connection.
SOCKS5 connection failed: Socks handshake failed
The SOCKS5 proxy initiated a handshake but failed to complete it, often due to incorrect SOCKS protocol negotiation, unsupported authentication methods, or an invalid target address/port provided during the SOCKS request.
fix
Ensure the SOCKS proxy is indeed a SOCKSv5 server. If using authentication, double-check `socksUsername` and `socksPassword` are correct and supported by the proxy. Verify that the `TARGET_HOST` and `TARGET_PORT` are valid and allowed by the proxy's rules. Check proxy logs for more specific error details.
TypeError: Cannot read property 'flowing' of undefined
Reported issue in dependent packages (`socks5-http-client`) when used with newer Node.js versions (e.g., Node.js 14.17.0+), indicating potential compatibility breakage with stream APIs.
fix
This suggests a core incompatibility. Consider downgrading Node.js if possible, or migrate to a more actively maintained SOCKS client library that is compatible with your current Node.js version. There's no direct fix within `socks5-client` itself without patches.
Upgrade
Version history
1.2.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
socks5-client — npm install socks5-client · libregistry