fetch-socks

library1.3.3jsnpmunverified

Socks proxy for Node.js builtin `fetch` and `WebSocket`, leveraging Undici's dispatcher system. Supports SOCKS4, SOCKS5, proxy chaining, and TLS upgrades. TypeScript types included. Currently at v1.3.3, actively maintained. Compared to alternatives like `socks` or `socks-proxy-agent`, it integrates seamlessly with modern Node.js fetch and WebSocket APIs without monkey-patching.

networking

npm install fetch-socks

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FETCH-SOCKS

fetch-socks

networkingjavascriptv1.3.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

socksDispatcher

✓ import { socksDispatcher } from 'fetch-socks'

✗ const { socksDispatcher } = require('fetch-socks')

ESM-only; CJS require is unsupported as the package is type:module.

socksConnector

✓ import { socksConnector } from 'fetch-socks'

✗ import socksConnector from 'fetch-socks'

Named export, not default.

SocksProxies

✓ import type { SocksProxies } from 'fetch-socks'

✗ import { SocksProxies } from 'fetch-socks'

Type import for TypeScript; runtime import will cause error since it's a type.

Demonstrates basic usage: creating a SOCKS5 dispatcher and making an HTTPS fetch through it.

import { socksDispatcher } from 'fetch-socks'; const dispatcher = socksDispatcher({ type: 5, host: '::1', port: 1080, }); const response = await fetch('https://example.com', { dispatcher }); console.log(response.status); console.log(await response.text());

Debug

Known issues

gotchaThe global dispatcher symbol changed between undici versions; using the wrong symbol silently fails to set proxy globally.

fix

Use Symbol.for('undici.globalDispatcher.1') for undici <=7, and Symbol.for('undici.globalDispatcher.2') for undici >=8.

affects: >=1.0.0

breakingRequires Node.js >=18 or modern undici; builtin fetch is experimental before Node 21.

fix

Ensure Node.js 18+ with --experimental-fetch flag pre-21, or use undici explicitly.

affects: >=1.0.0

gotchaAn empty proxies array falls back to direct connection, not an error.

fix

If you intend to require a proxy, validate proxies.length > 0 before calling socksDispatcher.

affects: >=1.0.0

deprecatedfetch-socks v1.x uses Undici's internal Agent; future versions may drop support for older undici patterns.

fix

Stay updated with release notes; consider pinning undici to a known working version.

affects: >=1.0.0

Errors

Common errors & fixes

Error: No such symbol: socksDispatcher

Using CJS require() in an ESM-only package.

fix

Use dynamic import: const { socksDispatcher } = await import('fetch-socks');

TypeError: globalThis[Symbol.for('undici.globalDispatcher.X')] is not a function

Wrong symbol version for undici version in use.

fix

Check undici version and use correct symbol: 'undici.globalDispatcher.1' for <=7, 'undici.globalDispatcher.2' for >=8.

Error: connect ECONNREFUSED ::1:1080

SOCKS proxy is not running at specified host:port.

fix

Start the SOCKS proxy server or verify host/port configuration.

TypeError: fetch is not a function

Using builtin fetch in Node <18 without experimental flag or without undici polyfill.

fix

Use Node 18+ with --experimental-fetch, or install undici and import fetch from 'undici'.

Upgrade

Version history

1.3.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Kaciras/fetch-socks ↗

packagefetch-socks ↗

homepagehttps://github.com/Kaciras/fetch-socks#readme ↗