{"id":15833,"library":"socks5-client","title":"SOCKS5 Client for Node.js","description":"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.","status":"maintenance","version":"1.2.8","language":"javascript","source_language":"en","source_url":"https://github.com/mattcg/socks5-client","tags":["javascript","socks5","socksv5","socks","v5","client","socket"],"install":[{"cmd":"npm install socks5-client","lang":"bash","label":"npm"},{"cmd":"yarn add socks5-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add socks5-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { SocksClient } from 'socks5-client';","symbol":"SocksClient","correct":"const SocksClient = require('socks5-client');"},{"note":"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.","wrong":"const client = SocksClient(options);","symbol":"SocksClient (instantiation)","correct":"const client = new SocksClient(options);"},{"note":"Methods generally use a callback-style API. There are no built-in Promise-based equivalents; manual promisification is required for modern async/await patterns.","wrong":"client.connectAsync(port, host, callback);","symbol":"SocksClient methods","correct":"client.connect(port, host, callback);"}],"quickstart":{"code":"const net = require('net');\nconst SocksClient = require('socks5-client');\n\nconst PROXY_HOST = process.env.SOCKS5_PROXY_HOST || '127.0.0.1';\nconst PROXY_PORT = parseInt(process.env.SOCKS5_PROXY_PORT || '1080', 10);\nconst TARGET_HOST = 'example.com';\nconst TARGET_PORT = 80;\n\n// Create a raw TCP socket to connect to the SOCKS5 proxy\nconst proxySocket = net.connect(PROXY_PORT, PROXY_HOST, () => {\n  console.log(`Connected to SOCKS5 proxy at ${PROXY_HOST}:${PROXY_PORT}`);\n\n  // Instantiate SocksClient with the proxy connection\n  const socksClient = new SocksClient();\n\n  // Initiate the SOCKS5 handshake to connect to the target host\n  socksClient.connect(\n    TARGET_PORT,\n    TARGET_HOST,\n    // Optional: add 'socksUsername', 'socksPassword' to options for auth\n    // { socksUsername: 'user', socksPassword: 'pass' },\n    proxySocket, // Pass the connected proxySocket\n    (err, destinationSocket) => {\n      if (err) {\n        console.error('SOCKS5 connection failed:', err.message);\n        proxySocket.end();\n        return;\n      }\n      console.log(`Successfully connected to ${TARGET_HOST}:${TARGET_PORT} via SOCKS5 proxy.`);\n\n      // Now destinationSocket is the proxied socket, ready for application data\n      const request = [\n        'GET / HTTP/1.1',\n        `Host: ${TARGET_HOST}`,\n        'Connection: close',\n        '',\n        ''\n      ].join('\\r\\n');\n\n      destinationSocket.write(request);\n\n      destinationSocket.on('data', (data) => {\n        console.log('Received data from target:', data.toString().substring(0, 200) + '...');\n      });\n\n      destinationSocket.on('end', () => {\n        console.log('Target connection ended.');\n        proxySocket.end();\n      });\n\n      destinationSocket.on('error', (data) => {\n        console.error('Target socket error:', data.message);\n        proxySocket.end();\n      });\n    }\n  );\n});\n\nproxySocket.on('error', (err) => {\n  console.error('Proxy socket error:', err.message);\n});\n","lang":"javascript","description":"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."},"warnings":[{"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';`.","message":"This 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`).","severity":"gotcha","affected_versions":">=1.0.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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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';`.","cause":"Attempting to import a CommonJS-only package (`socks5-client`) using ES Module syntax (`import { SocksClient } from 'socks5-client';`) in a Node.js ESM project.","error":"TypeError: (0 , _socks5Client.default) is not a constructor"},{"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.","cause":"The SOCKS5 proxy server is not running, is inaccessible, or the provided `proxy_host` or `proxy_port` is incorrect.","error":"Error: connect ECONNREFUSED <proxy_host>:<proxy_port>"},{"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.","cause":"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.","error":"SOCKS5 connection failed: Socks handshake failed"},{"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.","cause":"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.","error":"TypeError: Cannot read property 'flowing' of undefined"}],"ecosystem":"npm"}