PAC Proxy Agent

9.0.1 · active · verified Tue Apr 21

`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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `pac-proxy-agent` using `require()` syntax in a CommonJS context or an older Node.js project.

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.
```
TypeError: PacProxyAgent is not a constructor
```
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.

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(...))`.
```
Error: This module requires Node.js version >= 20.
```
cause The package's `engines` field specifies a minimum Node.js version of 20, and the current Node.js runtime is older.

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.

Warnings

breaking `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.
Fix: Upgrade your Node.js environment to version 20 or newer. Consider using a Node.js version manager like `nvm`.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install pac-proxy-agent npm
yarn add pac-proxy-agent yarn
pnpm add pac-proxy-agent pnpm

Imports

PacProxyAgent
wrong:
```
const { PacProxyAgent } = require('pac-proxy-agent');
```
correct:
```
import { PacProxyAgent } from 'pac-proxy-agent';
```
The package is ESM-only since v9.0.0, requiring Node.js >= 20 and `import` syntax.

Quickstart

Demonstrates initializing `PacProxyAgent` with a PAC file URL and using it with Node.js's built-in `http.get`.

import * as http from 'http';
import { PacProxyAgent } from 'pac-proxy-agent';

const pacFileUrl = process.env.PAC_FILE_URL ?? 'pac+https://cloudup.com/ceGH2yZ0Bjp+';
const targetUrl = process.env.TARGET_URL ?? 'http://nodejs.org/api/';

const agent = new PacProxyAgent(pacFileUrl);

console.log(`Attempting to fetch ${targetUrl} using PAC file from ${pacFileUrl}`);

http.get(targetUrl, { agent }, (res) => {
  console.log(`Successfully connected! Status: ${res.statusCode}`);
  console.log('Response Headers:', res.headers);
  res.pipe(process.stdout);
}).on('error', (err) => {
  console.error('Error fetching URL:', err.message);
  process.exit(1);
});

view raw JSON →