{"id":16165,"library":"pac-proxy-agent","title":"PAC Proxy Agent","description":"`pac-proxy-agent` is a Node.js module that provides an `http.Agent` implementation for resolving proxy settings using a Proxy Auto-Configuration (PAC) file. It is part of the actively maintained `proxy-agents` monorepo by TooTallNate and is currently at version `9.0.1`. This agent seamlessly integrates with Node.js's native `http` and `https` modules, automatically determining whether to use a direct connection, an HTTP proxy, an HTTPS proxy, or a SOCKS proxy based on the PAC file's logic for a given target URL. Releases typically follow the monorepo's cadence, often aligning major version bumps with Node.js LTS updates, such as the recent shift to Node.js 20. Its key differentiator is its robust and secure PAC file interpretation, leveraging `quickjs-wasi` for isolated PAC script execution.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/TooTallNate/proxy-agents","tags":["javascript","pac","proxy","agent","http","https","socks","request","access"],"install":[{"cmd":"npm install pac-proxy-agent","lang":"bash","label":"npm"},{"cmd":"yarn add pac-proxy-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add pac-proxy-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Resolves PAC file logic to determine proxy for a given URL.","package":"pac-resolver"},{"reason":"Base class for all `http.Agent` implementations in the `proxy-agents` family.","package":"agent-base"},{"reason":"Used internally for HTTP proxy connections resolved by the PAC file.","package":"http-proxy-agent"},{"reason":"Used internally for HTTPS proxy connections resolved by the PAC file.","package":"https-proxy-agent"},{"reason":"Used internally for SOCKS proxy connections resolved by the PAC file.","package":"socks-proxy-agent"}],"imports":[{"note":"The package is ESM-only since v9.0.0, requiring Node.js >= 20 and `import` syntax.","wrong":"const { PacProxyAgent } = require('pac-proxy-agent');","symbol":"PacProxyAgent","correct":"import { PacProxyAgent } from 'pac-proxy-agent';"}],"quickstart":{"code":"import * as http from 'http';\nimport { PacProxyAgent } from 'pac-proxy-agent';\n\nconst pacFileUrl = process.env.PAC_FILE_URL ?? 'pac+https://cloudup.com/ceGH2yZ0Bjp+';\nconst targetUrl = process.env.TARGET_URL ?? 'http://nodejs.org/api/';\n\nconst agent = new PacProxyAgent(pacFileUrl);\n\nconsole.log(`Attempting to fetch ${targetUrl} using PAC file from ${pacFileUrl}`);\n\nhttp.get(targetUrl, { agent }, (res) => {\n  console.log(`Successfully connected! Status: ${res.statusCode}`);\n  console.log('Response Headers:', res.headers);\n  res.pipe(process.stdout);\n}).on('error', (err) => {\n  console.error('Error fetching URL:', err.message);\n  process.exit(1);\n});","lang":"typescript","description":"Demonstrates initializing `PacProxyAgent` with a PAC file URL and using it with Node.js's built-in `http.get`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer. Consider using a Node.js version manager like `nvm`.","message":"`pac-proxy-agent` v9.0.0 and later require Node.js version 20 or higher. Running on older Node.js versions will lead to installation failures or runtime errors.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Convert your module to ESM by using `import` statements and ensuring your `package.json` has `\"type\": \"module\"` or that your file uses a `.mjs` extension. This change is directly related to the Node.js 20 minimum requirement.","message":"As of v9.0.0, `pac-proxy-agent` is an ECMAScript Module (ESM) only package. Direct `require()` statements for importing it are no longer supported and will result in an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Validate your PAC file syntax using a linter or online tool. Ensure the PAC file URL is always reachable and returns a valid JavaScript. Implement robust error handling around connections when using the agent.","message":"The `PacProxyAgent` relies on fetching and executing a PAC file. Issues such as network inaccessibility of the PAC URL, invalid PAC file syntax, or slow PAC file resolution can lead to connection failures or performance bottlenecks. Ensure the PAC URL is reliable and the script is valid.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are on `pac-proxy-agent` v9.0.1 or newer to benefit from these stability improvements. No direct code changes are typically required unless you're interacting with `pac-resolver` directly.","message":"Recent updates (v9.0.1) to the underlying `pac-resolver` dependency improved PAC script execution stability by updating QuickJS integration. While not a direct API change for `pac-proxy-agent`, it ensures more robust and performant PAC parsing internally, reducing obscure runtime issues related to PAC script execution.","severity":"gotcha","affected_versions":">=9.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Convert your module to use ECMAScript `import` statements. For CommonJS projects, consider using dynamic `import()` or upgrading your project to `type: \"module\"` in `package.json` and ensure Node.js >= 20.","cause":"Attempting to import `pac-proxy-agent` using `require()` syntax in a CommonJS context or an older Node.js project.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using `import { PacProxyAgent } from 'pac-proxy-agent';` and that your Node.js environment is version 20 or newer, configured for ESM. If dynamically importing in a CommonJS module, use `import('pac-proxy-agent').then(m => new m.PacProxyAgent(...))`.","cause":"This error often occurs when attempting to instantiate `PacProxyAgent` incorrectly, typically by using CommonJS `require()` or by misunderstanding named vs. default imports, especially in environments where module interop is tricky.","error":"TypeError: PacProxyAgent is not a constructor"},{"fix":"Upgrade your Node.js environment to version 20 or newer. Tools like `nvm` (Node Version Manager) can help manage multiple Node.js versions on your system.","cause":"The package's `engines` field specifies a minimum Node.js version of 20, and the current Node.js runtime is older.","error":"Error: This module requires Node.js version >= 20."}],"ecosystem":"npm"}