# fetch-socks

> Socks proxy for Node builtin `fetch`

Latest version **1.3.3** (published 2026-04-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install fetch-socks
pnpm add fetch-socks
yarn add fetch-socks
bun add fetch-socks
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.3.3 |
| Published | 2026-04-04 |
| First published | 2022-11-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 10.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 46 |
| Author | Kaciras |
| Maintainers | kaciras |
| Keywords | fetch, socks, proxy, undici |

## Links

- npm: https://www.npmjs.com/package/fetch-socks
- Repository: https://github.com/Kaciras/fetch-socks
- Homepage: https://github.com/Kaciras/fetch-socks#readme
- Issues: https://github.com/Kaciras/fetch-socks/issues
- npm.io page: https://npm.io/package/fetch-socks

## Dependencies (2)

- [socks](https://npm.io/package/socks.md) ^2.8.7
- [undici](https://npm.io/package/undici.md) >=7

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 1.3.3 (latest) — 2026-04-04
- 1.3.2 — 2024-11-29
- 1.3.1 — 2024-11-28
- 1.3.0 — 2024-03-22
- 1.2.0 — 2022-12-12
- 1.1.0 — 2022-11-30
- 1.0.1 — 2022-11-29
- 1.0.0 — 2022-11-28

## README

# fetch-socks

[![npm package](https://img.shields.io/npm/v/fetch-socks.svg)](https://npmjs.com/package/fetch-socks)
[![Test](https://github.com/Kaciras/fetch-socks/actions/workflows/test.yml/badge.svg)](https://github.com/Kaciras/fetch-socks/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/Kaciras/fetch-socks/branch/master/graph/badge.svg?token=DJLSKIKYBJ)](https://codecov.io/gh/Kaciras/fetch-socks)
[![type-coverage](https://img.shields.io/badge/dynamic/json?label=type-coverage&prefix=%E2%89%A5&query=%24.typeCoverage.atLeast&suffix=%25&url=https%3A%2F%2Fraw.githubusercontent.com%2FKaciras%2Ffetch-socks%2Fmaster%2Fpackage.json)](https://github.com/plantain-00/type-coverage)

Socks proxy for Node builtin (also [undici](https://github.com/nodejs/undici)) `fetch` and `WebSocket`.

```shell
npm install fetch-socks
```

# Usage Examples

Fetch `http://example.com` through `socks5://[::1]:1080`.

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({
    type: 5,
    host: "::1",
    port: 1080,

    //userId: "username",
    //password: "password",
});

const response = await fetch("https://example.com", { dispatcher });
console.log(response.status);
console.log(await response.text());
```

Set the proxy globally.

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({ /* ... */});

// For undici <= 7
global[Symbol.for("undici.globalDispatcher.1")] = dispatcher;

// For undici >= 8
global[Symbol.for("undici.globalDispatcher.2")] = dispatcher;
````

TypeScript example, fetch through proxy chain with two SOCKS proxies.

```typescript
import { fetch } from "undici";
import { socksDispatcher, SocksProxies } from "fetch-socks";

const proxyConfig: SocksProxies = [{
    type: 5,
    host: "::1",
    port: 1080,
}, {
    type: 5,
    host: "127.0.0.1",
    port: 1081,
}];

const dispatcher = socksDispatcher(proxyConfig, {
    connect: {
        // set some TLS options
        rejectUnauthorized: false,
    },
});

const response = await fetch("https://example.com", { dispatcher });
```

create a socks connection over HTTP tunnel with `socksConnector`.

```javascript
import { Client, Agent } from "undici";
import { socksConnector } from "fetch-socks";

const socksConnect = socksConnector({
    type: 5,
    host: "::1",
    port: 1080,
});

async function connect(options, callback) {
    // First establish a connection to the HTTP proxy server (localhost:80).
    const client = new Client("http://localhost:80");
    const { socket, statusCode } = await client.connect({
        // Tell the server to connect to the next ([::1]:1080)
        path: "[::1]:1080",
    });
    if (statusCode !== 200) {
        callback(new Error("Proxy response !== 200 when HTTP Tunneling"));
    } else {
        // Perform socks handshake on the connection.
        socksConnect({ ...options, httpSocket: socket }, callback);
    }
}

const dispatcher = new Agent({ connect });
const response = await fetch("https://example.com", { dispatcher });
```

It also can proxy WebSocket:

```javascript
import { socksDispatcher } from "fetch-socks";

const dispatcher = socksDispatcher({ /* ... */});
const ws = new WebSocket(`ws://example.com`, { dispatcher });
```

# API

## `socksConnector(proxies, connectOptions?)`

Create an [Undici connector](https://undici.nodejs.org/#/docs/api/Connector) which establish the connection through socks proxies.

* `proxies` The proxy server to use or the list of proxy servers to chain. If you pass an empty array it will connect directly.
* `connectOptions` (optional) The options used to perform directly connect or TLS upgrade, see [here](https://undici.nodejs.org/#/docs/api/Connector?id=parameter-buildconnectorbuildoptions)

## `socksDispatcher(proxies, options?)`

Create a Undici Agent with socks connector.

* `proxies` Same as `socksConnector`'s.
* `options` (optional) [Agent options](https://undici.nodejs.org/#/docs/api/Agent). The `connect` property will be used to create socks connector.

```javascript
import { socksConnector, socksDispatcher } from "fetch-socks";
import { Agent } from "undici";

const proxy = { type: 5, host: "::1", port: 1080 };
const connect = { /* ... */ };
const agentOptions = { /* ... */ };

socksDispatcher(proxy, { ...agentOptions, connect });

// Is equivalent to
new Agent({ ...agentOptions, connect: socksConnector(proxy, connect) });
```

---
_Source: https://npm.io/package/fetch-socks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._