SOCKS5 HTTPS Client for Node.js

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module context.
  fix Ensure your file is treated as CommonJS (e.g., `.js` file without `"type": "module"` in `package.json`, or explicitly `.cjs` extension) or use a modern, ESM-compatible SOCKS proxy client.

• TypeError: shttps.get is not a function

  cause Incorrect import of the `shttps` object when attempting an ES Module import.
  fix This package exports a default CommonJS module. Use `const shttps = require('socks5-https-client');` instead of `import shttps from 'socks5-https-client';`.

• Error: self-signed certificate in certificate chain

  cause The HTTPS server uses a self-signed or untrusted certificate, and `rejectUnauthorized` is true (the default).
  fix For testing or specific scenarios, set `rejectUnauthorized: false` in the options. For production, ensure the SOCKS proxy is correctly configured or the target server has a trusted certificate.

Warnings

• breaking This package is CommonJS-only and does not support ES Modules natively. Attempting to `import` it will result in errors in modern Node.js ESM environments.
  Fix: Use `const someVar = require('package')` syntax. If your project is pure ESM, you may need a wrapper or alternative package.
• gotcha The package is effectively abandoned, with the last release in 2013 and no recent maintenance. This means it may not be compatible with newer Node.js versions (e.g., >v16, >v18), recent OpenSSL changes, or security best practices.
  Fix: For new projects, consider modern, actively maintained SOCKS proxy client libraries, or use a reverse proxy that handles SOCKS for you. For existing projects, thoroughly test against your target Node.js version.
• gotcha This library only supports HTTPS requests. For plain HTTP requests through SOCKSv5, a separate package `socks5-http-client` from the same author is required.
  Fix: If you need both HTTP and HTTPS, you must import and use `socks5-http-client` for HTTP and `socks5-https-client` for HTTPS.
• gotcha Node.js engine requirement is `>= 6.4.0`. While it might run on newer versions, its lack of updates means it has not been tested or optimized for changes in Node.js runtime, especially concerning networking or TLS.
  Fix: Verify compatibility with your target Node.js version through extensive testing. Be prepared for potential TLS handshake errors or deprecated API warnings on very new Node.js versions.

Install

• npm install socks5-https-client npm
• yarn add socks5-https-client yarn
• pnpm add socks5-https-client pnpm

Imports

• shttps
  wrong:

  import shttps from 'socks5-https-client';

  correct:

  const shttps = require('socks5-https-client');

  This package is CommonJS-only. Direct ESM imports will fail. `shttps` is the main entry point for `get` and `request` methods.
• Agent
  wrong:

  import { Agent } from 'socks5-https-client/lib/Agent';

  correct:

  const Agent = require('socks5-https-client/lib/Agent');

  The `Agent` class for integration with libraries like `request` is found via a deep import path and is CommonJS-only.
• get
  wrong:

  import { get } from 'socks5-https-client';

  correct:

  const shttps = require('socks5-https-client');
  shttps.get(...);

  The `get` function is a method on the `shttps` object returned by the main require call, not a named export.

Quickstart

Demonstrates making an HTTPS GET request through a SOCKSv5 proxy using the `shttps.get` method, with basic error handling.

const shttps = require('socks5-https-client');

shttps.get({
	hostname: 'encrypted.google.com',
	path: '/',
	rejectUnauthorized: true, // This is the default.
    socksHost: 'localhost',
    socksPort: 1080 // Default SOCKS port
}, function(res) {
	res.setEncoding('utf8');
	res.on('readable', function() {
		process.stdout.write(res.read()); // Log response to console.
	});
    res.on('end', () => {
        console.log('\nHTTPS request through SOCKS5 completed.');
    });
    res.on('error', (err) => {
        console.error('Response error:', err.message);
    });
}).on('error', (err) => {
    console.error('Request error:', err.message);
});