{"id":16828,"library":"httpxy","title":"HTTP and WebSocket Proxy for Node.js","description":"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.","status":"active","version":"0.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/httpxy","tags":["javascript","typescript"],"install":[{"cmd":"npm install httpxy","lang":"bash","label":"npm"},{"cmd":"yarn add httpxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add httpxy","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"httpxy is an ESM-first package and ships with TypeScript types. Use named imports.","wrong":"const { proxyFetch } = require('httpxy');","symbol":"proxyFetch","correct":"import { proxyFetch } from 'httpxy';"},{"note":"Used for standalone WebSocket upgrade proxying, it's a named export.","wrong":"const proxyUpgrade = require('httpxy').proxyUpgrade;","symbol":"proxyUpgrade","correct":"import { proxyUpgrade } from 'httpxy';"},{"note":"`createProxyServer` is a factory function and a named export. Ensure to use named imports.","wrong":"const createProxyServer = require('httpxy');\nconst proxy = createProxyServer({});","symbol":"createProxyServer","correct":"import { createProxyServer } from 'httpxy';"}],"quickstart":{"code":"import { createServer } from 'node:http';\nimport { createProxyServer } from 'httpxy';\n\nconst proxy = createProxyServer({});\n\nconst server = createServer(async (req, res) => {\n  try {\n    // Replace with your target server's address\n    const targetAddress = process.env.PROXY_TARGET_URL ?? 'http://127.0.0.1:8080';\n    await proxy.web(req, res, {\n      target: targetAddress\n    });\n  } catch (error) {\n    console.error('Proxy error:', error);\n    res.statusCode = 500;\n    res.end('Proxy error: ' + String(error));\n  }\n});\n\nconst port = process.env.PORT ?? 3000;\nserver.listen(port, () => {\n  console.log(`Proxy is listening on http://localhost:${port}`);\n  console.log('Ensure a target server is running at', process.env.PROXY_TARGET_URL || 'http://127.0.0.1:8080');\n});","lang":"typescript","description":"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."},"warnings":[{"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 })`).","message":"Starting 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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.2.0 <0.3.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.6"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Proxy error: connect ECONNREFUSED"},{"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.","cause":"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.","error":"Error: WebSocket was closed before the connection was established."},{"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`.","cause":"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.","error":"Applications on high load exhibit poor performance or excessive socket creation."}],"ecosystem":"npm","meta_description":null}