pac-proxy-agent 9.x

Complete instructions

Verified against pac-proxy-agent@9.1.0 on 2026-09-08. 2 of 2 examples executed.

pac-proxy-agent

Scope and runtime

pac-proxy-agent provides an http.Agent for Node's built-in http and https modules. It retrieves a PAC file, evaluates it, and selects an HTTP, HTTPS, SOCKS, or direct connection for each request.

The 9.x line requires Node.js 20 or newer and is ESM-only. Import PacProxyAgent by name; do not use the CommonJS require() shape shown in older examples.

Constructor

new PacProxyAgent(uri: string | URL, options?)

The PAC source protocols exposed by the package are:

• pac+data:
• pac+file:
• pac+ftp:
• pac+http:
• pac+https:

The underlying URI is loaded after removing the pac+ prefix. The constructor also accepts the corresponding underlying URI protocols according to the package source.

Options combine Node http.Agent options with PAC resolver, URI-loading, HTTP proxy, HTTPS proxy, and SOCKS proxy options. The package-specific option is:

fallbackToDirect?: boolean

Pass the resulting agent to Node's built-in HTTP APIs with { agent }:

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

const agent = new PacProxyAgent('pac+https://example.invalid/proxy.pac');
http.get('http://example.invalid/', { agent }, (res) => {
  res.resume();
});

A request is needed for connection selection and proxy-agent creation. The package is not itself a request client.

Resolving a PAC file without making a request

getResolver() loads the PAC source lazily and returns the callable FindProxyForURL resolver. Calling it directly is useful when code needs to inspect the PAC decision without issuing an HTTP request.

This standalone example uses a data: PAC source, so it needs no network or filesystem access:

import assert from 'node:assert/strict';
import { PacProxyAgent } from 'pac-proxy-agent';

const pac = `
function FindProxyForURL(url, host) {
  if (host === 'internal.example') return 'DIRECT';
  return 'PROXY proxy.example:8080';
}
`;

const agent = new PacProxyAgent(
  `pac+data:text/plain,${encodeURIComponent(pac)}`
);

const resolver = await agent.getResolver();
assert.equal(await resolver('http://internal.example/', 'internal.example'), 'DIRECT');
assert.equal(
  await resolver('http://external.example/', 'external.example'),
  'PROXY proxy.example:8080'
);

The resolver is loaded and cached lazily. Reusing the agent allows the implementation to reuse the existing resolver when the PAC content has not changed.

Static protocol list

The class exposes the PAC protocols it handles through PacProxyAgent.protocols:

import assert from 'node:assert/strict';
import { PacProxyAgent } from 'pac-proxy-agent';

assert.deepEqual(PacProxyAgent.protocols, [
  'pac+data',
  'pac+file',
  'pac+ftp',
  'pac+http',
  'pac+https',
]);

Common mistakes

• Do not copy pre-8.x CommonJS examples. Version 9 is ESM and requires Node.js 20 or newer.
• Do not instantiate the agent with an ordinary PAC URL while forgetting the PAC scheme expected by the package. PAC sources are represented with schemes such as pac+http:, pac+https:, or pac+data:.
• Do not expect PacProxyAgent to execute a PAC decision merely by constructing it. PAC loading is lazy; call getResolver() or use the agent in a Node HTTP request.
• Do not use describe, it, expect, or runner-provided globals in a direct script. The agent integrates with Node's http and https APIs rather than providing a test-runner interface.
• Do not assume an agent is a standalone request client. Requests must be made through Node's built-in HTTP APIs with the agent supplied in the request options.
• Do not rely on older 7.x implementation details involving CommonJS imports or the older QuickJS runtime. The 8.x and 9.x lines changed those internals; 9.x uses the package's ESM setup and requires Node 20 or newer.

What this skill does not cover

This skill does not cover the behavior of the underlying get-uri, PAC resolver, QuickJS runtime, HTTP proxy agent, HTTPS proxy agent, or SOCKS proxy agent packages individually. It does not cover PAC-file authoring beyond the resolver examples, proxy authentication, detailed option behavior, error handling, or running real HTTP/HTTPS requests through a network or filesystem-backed PAC source. Those behaviors require the package's own runtime dependencies and an actual Node HTTP request environment.