Registry / http-networking / pac-proxy-agent

pac-proxy-agent

library9.0.1jsnpmunverified

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

http-networking

npm install pac-proxy-agent

github ↗package ↗

INSTALL

IMPORT

SIG · PAC-PROXY-AGENT

pac-proxy-agent

http-networkingjavascriptv9.0.1

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.

PacProxyAgent

✓ import { PacProxyAgent } from 'pac-proxy-agent';

✗ const { PacProxyAgent } = require('pac-proxy-agent');

The package is ESM-only since v9.0.0, requiring Node.js >= 20 and `import` syntax.

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); });

Debug

Known issues

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

affects: >=9.0.0

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

affects: >=9.0.0

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

affects: >=1.0.0

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

affects: >=9.0.1

Errors

Common errors & fixes

ERR_REQUIRE_ESM

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

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.

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.

Upgrade

Version history

9.0.1latest on npm

Audit

Dependencies

pac-resolverrequiredResolves PAC file logic to determine proxy for a given URL.

agent-baserequiredBase class for all `http.Agent` implementations in the `proxy-agents` family.

http-proxy-agentrequiredUsed internally for HTTP proxy connections resolved by the PAC file.

https-proxy-agentrequiredUsed internally for HTTPS proxy connections resolved by the PAC file.

socks-proxy-agentrequiredUsed internally for SOCKS proxy connections resolved by the PAC file.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/TooTallNate/proxy-agents ↗

packagehttps://www.npmjs.com/package/pac-proxy-agent ↗