httpxy

library0.0.0a1jsnpmunverified

httpxy is a performant and feature-rich HTTP and WebSocket proxy library for Node.js, currently at version `0.5.1`. It maintains an active release cadence with frequent minor and patch updates, as evidenced by recent versions like v0.5.1, v0.5.0, v0.4.0, and v0.3.0. The library offers three primary interfaces: `proxyFetch` for modern web-standard `Request`/`Response` based proxying, `proxyUpgrade` for standalone WebSocket upgrade handling without a full server instance, and `createProxyServer` which provides a more traditional, event-driven HTTP proxy server, originally forked from `node-http-proxy`. Key differentiators include its adoption of web-standard APIs, explicit WebSocket proxying capabilities, and performance optimizations inspired by libraries like `fast-proxy`. It ships with comprehensive TypeScript types, ensuring robust development in typed environments.

http-networking web-framework

npm install httpxy

github ↗package ↗

INSTALL

IMPORT

SIG · HTTPXY

httpxy

http-networkingjavascriptv0.0.0a1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

proxyFetch

✓ import { proxyFetch } from 'httpxy';

✗ const { proxyFetch } = require('httpxy');

httpxy is an ESM-first package and ships with TypeScript types. Use named imports.

proxyUpgrade

✓ import { proxyUpgrade } from 'httpxy';

✗ const proxyUpgrade = require('httpxy').proxyUpgrade;

Used for standalone WebSocket upgrade proxying, it's a named export.

createProxyServer

✓ import { createProxyServer } from 'httpxy';

✗ const createProxyServer = require('httpxy'); const proxy = createProxyServer({});

`createProxyServer` is a factory function and a named export. Ensure to use named imports.

This quickstart demonstrates setting up a basic HTTP proxy server using `createProxyServer`. It listens on a specified port and forwards incoming requests to a configurable target URL, handling potential proxy errors gracefully.

import { createServer } from 'node:http'; import { createProxyServer } from 'httpxy'; const proxy = createProxyServer({}); const server = createServer(async (req, res) => { try { // Replace with your target server's address const targetAddress = process.env.PROXY_TARGET_URL ?? 'http://127.0.0.1:8080'; await proxy.web(req, res, { target: targetAddress }); } catch (error) { console.error('Proxy error:', error); res.statusCode = 500; res.end('Proxy error: ' + String(error)); } }); const port = process.env.PORT ?? 3000; server.listen(port, () => { console.log(`Proxy is listening on http://localhost:${port}`); console.log('Ensure a target server is running at', process.env.PROXY_TARGET_URL || 'http://127.0.0.1:8080'); });

Debug

Known issues

breakingStarting with v0.5.0, `ProxyServer` and `proxyFetch` now utilize shared `http.Agent`/`https.Agent` instances with `keepAlive: true` by default. This enables connection pooling (256 max sockets, 64 max free sockets) instead of creating a new socket per request. This change significantly affects resource usage and connection behavior.

fix

To revert to the pre-v0.5.0 behavior of creating a new socket per request, set `agent: false` in the options for `proxy.web` (e.g., `proxy.web(req, res, { target, agent: false })`) or `proxyFetch` (e.g., `proxyFetch(target, url, { agent: false })`).

affects: >=0.5.0

breakingThe v0.2.0 release included a significant 'Code improvements' refactor, marked with a breaking change warning. While specific API breakages were not detailed, this suggests potential changes in internal behavior or less common use cases. Developers upgrading from pre-v0.2.0 should proceed with caution.

fix

Thoroughly review your proxy configurations and test applications when upgrading from versions prior to v0.2.0. Consult the changelog for any subtle behavioral changes that might impact your specific use case, though no explicit API changes were documented.

affects: >=0.2.0 <0.3.0

gotchaThe `followRedirects` option has seen evolving support and default behavior across different versions and proxy methods. It was initially noted as unsupported in v0.1.6, then native support was added in v0.3.0, and `proxyFetch` gained explicit `followRedirects` options in v0.4.0. For `proxyFetch`, redirects are handled manually by default, meaning automatic following requires explicit configuration.

fix

When using `proxyFetch`, explicitly set the `followRedirects` option if automatic redirect following is desired. For `ProxyServer`, consult the latest documentation for the specific `followRedirects` behavior and its configuration, as defaults and availability might vary.

affects: >=0.1.6

Errors

Common errors & fixes

Proxy error: connect ECONNREFUSED

The target server that the `httpxy` instance is configured to proxy requests to is either not running, not listening on the specified address/port, or is unreachable due to network configuration or firewalls.

fix

Verify that the target server (e.g., `http://127.0.0.1:8080` in examples) is actively running and listening on the correct host and port. Ensure network connectivity between the `httpxy` server and the target server.

Error: WebSocket was closed before the connection was established.

When using `proxyUpgrade`, this error indicates that the target server for the WebSocket upgrade request did not properly respond to the WebSocket handshake, or the connection was terminated prematurely.

fix

Ensure the target server specified in `proxyUpgrade` is correctly configured to handle WebSocket upgrade requests and that no intermediate proxies or firewalls are interfering with the WebSocket handshake. Check server logs for errors related to WebSocket connections.

Applications on high load exhibit poor performance or excessive socket creation.

This can occur if the default `keepAlive` connection pooling (introduced in v0.5.0) is inadvertently disabled, or if using an older version of `httpxy` that predates this feature.

fix

For `httpxy` versions >= v0.5.0, ensure that `agent: false` is *not* set in your `ProxyServer` or `proxyFetch` options if you intend to leverage the default keep-alive connection pooling. If more granular control is needed, provide a custom `http.Agent` or `https.Agent` instance configured with `keepAlive: true`.

Upgrade

Version history

0.0.0a1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unjs/httpxy ↗

packagehttps://www.npmjs.com/package/httpxy ↗