{"id":16072,"library":"http-proxy-agent","title":"HTTP Proxy Agent","description":"`http-proxy-agent` provides a robust `http.Agent` implementation designed for making HTTP requests through an HTTP or HTTPS proxy server in Node.js environments. Currently at version 9.0.0, this library is part of the actively maintained `proxy-agents` monorepo, which generally sees updates aligned with Node.js LTS releases. Its primary function is to integrate seamlessly with Node's built-in `http` module, abstracting the proxy connection details. A key distinction is its specific focus on `http` module requests; for proxying `https` module requests, the companion `https-proxy-agent` package should be used. It supports standard `http.Agent` options and allows for custom headers to be sent to the proxy. This package is specifically designed for Node.js environments, requiring Node.js 20 or later for version 9.0.0.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/TooTallNate/proxy-agents","tags":["javascript","http","proxy","endpoint","agent"],"install":[{"cmd":"npm install http-proxy-agent","lang":"bash","label":"npm"},{"cmd":"yarn add http-proxy-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-proxy-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core abstraction for creating custom `http.Agent` implementations, managing common agent functionalities.","package":"agent-base","optional":false}],"imports":[{"note":"This package is ESM-first since v9. While CommonJS `require` might work via transpilation or bundlers, direct CJS usage is discouraged and may lead to issues.","wrong":"const HttpProxyAgent = require('http-proxy-agent').HttpProxyAgent;","symbol":"HttpProxyAgent","correct":"import { HttpProxyAgent } from 'http-proxy-agent';"},{"note":"Import types separately when only needing the type definition for static analysis.","symbol":"HttpProxyAgentOptions","correct":"import type { HttpProxyAgentOptions } from 'http-proxy-agent';"},{"note":"The primary class `HttpProxyAgent` is a named export, not a default export.","wrong":"import HttpProxyAgent from 'http-proxy-agent';","symbol":"default","correct":"import { HttpProxyAgent } from 'http-proxy-agent';"}],"quickstart":{"code":"import * as http from 'http';\nimport { HttpProxyAgent } from 'http-proxy-agent';\n\n// Replace with your actual proxy URL and target URL\nconst proxyUrl = process.env.HTTP_PROXY_URL ?? 'http://127.0.0.1:3128';\nconst targetUrl = process.env.TARGET_URL ?? 'http://example.com/api/';\n\nconst agent = new HttpProxyAgent(proxyUrl);\n\nhttp.get(targetUrl, { agent }, (res) => {\n  console.log(`Proxying request to ${targetUrl} via ${proxyUrl}`);\n  console.log('Response status:', res.statusCode);\n  console.log('Response headers:', res.headers);\n  // Log a portion of the response body to show it's working\n  res.on('data', (chunk) => {\n    process.stdout.write(chunk.toString().substring(0, 100) + '...');\n  });\n  res.on('end', () => {\n    console.log('\\n--- Request complete ---');\n  });\n}).on('error', (err) => {\n  console.error('Request failed:', err.message);\n});","lang":"typescript","description":"Demonstrates how to create and use an `HttpProxyAgent` instance with Node.js's built-in `http.get` method to route an HTTP request through a specified proxy server."},"warnings":[{"fix":"Upgrade your Node.js runtime environment to version 20 or newer to ensure compatibility and stability.","message":"The minimum Node.js version required for `http-proxy-agent` v9.0.0 and subsequent releases has been raised to Node.js 20. Running on older Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"For HTTPS requests, switch to using `import { HttpsProxyAgent } from 'https-proxy-agent';`.","message":"This `HttpProxyAgent` is specifically designed for proxying HTTP requests made using Node.js's `http` module. If you need to proxy HTTPS requests made with the `https` module (e.g., `https.get`), you must use the companion `https-proxy-agent` package instead.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Exercise caution when setting custom headers. Only include headers explicitly intended for the proxy or those you are comfortable being sent to the final destination endpoint.","message":"Custom headers provided in the `options.headers` object for the proxy agent may not be stripped by the proxy server and could be forwarded to the final destination server. This could lead to unintended information leakage or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Convert your project or relevant files to use ES Modules (`'type': 'module'` in `package.json` and `.mjs` files), or use dynamic `import()` if loading from a CJS module (`const { HttpProxyAgent } = await import('http-proxy-agent');`).","cause":"Attempting to use `require()` to import `http-proxy-agent` in a CommonJS module context, as the package is now primarily designed for ES Modules.","error":"ERR_REQUIRE_ESM"},{"fix":"Update your Node.js development and deployment environments to version 20 or newer.","cause":"The application is being executed on a Node.js runtime version older than 20, which does not meet the minimum requirement for `http-proxy-agent` v9.0.0.","error":"Error: This module requires Node.js >= 20"},{"fix":"Verify that the proxy server's IP address and port are correct, ensure the proxy service is running and accessible from your network, and check for any local or network firewall rules that might be blocking the connection.","cause":"The proxy server specified in the `HttpProxyAgent` URL is unreachable, not running, or actively refusing connections from your application.","error":"connect ECONNREFUSED <proxy_ip>:<proxy_port>"}],"ecosystem":"npm"}