How to Use NPM proxy-agent: Environment, Auth, and Checks

Install the compatible package in the application that will send the request:

npm install proxy-agent

The current package documentation uses an ES module import:

import { ProxyAgent } from 'proxy-agent';

Check your project's runtime, module system, and lockfile before copying code. A package example that runs in ESM may need an intentional adaptation in a CommonJS project. Do not change the entire module format just to make one snippet compile.

Put routing in the environment, not the source file

The package relies on proxy-related environment variables and the

proxy-from-env

.env.example

HTTPS_PROXY=http://USER:PASSWORD@proxy.example.test:8080
HTTP_PROXY=http://USER:PASSWORD@proxy.example.test:8080
NO_PROXY=localhost,127.0.0.1,.internal.example

The values above are fictional. For a real deployment, encode reserved characters in credentials and use the endpoint scheme provided in the assignment record.

NO_PROXY

Verify one HTTPS request

Create one

ProxyAgent

import https from 'node:https';
import { ProxyAgent } from 'proxy-agent';
const checkUrl = process.env.AUTHORIZED_IP_CHECK_URL;
if (!checkUrl) {
throw new Error('AUTHORIZED_IP_CHECK_URL is required');
}
const agent = new ProxyAgent();
const request = https.get(checkUrl, {
agent,
signal: AbortSignal.timeout(15000),
}, (response) => {
let body = '';
response.setEncoding('utf8');
response.on('data', (chunk) => {
body += chunk;
});
response.on('end', () => {
console.log('status', response.statusCode);
console.log('body', body);
});
});
request.on('error', (error) => {
console.error('request failed', error.name);
});

Separate authentication from application errors

When a request fails, preserve the order of events:

1. No proxy selected: inspect the effective environment and

   NO_PROXY

   match.
2. Connection error: verify the assigned host and port from the same runtime.
3. Authentication error or 407: replace the test credential through the secret store; do not print it.
4. TLS error: confirm the endpoint scheme and certificate policy rather than disabling verification.
5. Target HTTP error: record the status separately from proxy negotiation.
6. Timeout: identify whether the connection or response phase stalled before changing limits.

Do not solve certificate errors with a global setting that disables TLS verification. That turns a visible configuration problem into an invisible security risk.

Confirm what

NO_PROXY

actually bypasses

For repeatable tests, launch a clean process with the exact environment intended for the application. Shell profiles, containers, CI runners, and process managers can each inject different values.

Package support is not product support

The

proxy-agent

IPIPD currently identifies static IP and VPS as separate product categories. VPS is a server product, not a proxy type. This Node.js setup cannot establish whether a static IP is residential or ISP-classified, and it cannot prove speed, future access, account safety, or business outcomes.

A practical handoff record

Before another developer reuses the setup, record:

• package name and locked version;
• Node.js runtime version;
• which environment variable supplied the route;
• sanitized proxy host label and port;

• NO_PROXY

  policy;
• diagnostic target, timestamp, status, and observed address;
• rollback steps for removing temporary variables.

This record is more useful than a screenshot of a successful response because it explains why the route was selected.

Quick reference: how to verify the proxy-agent environment contract

For the field definitions, read the proxy host, port, and authentication guide. For a related Python client pattern, compare the Node.js fetch agent configuration guide. Confirm syntax against the official proxy-agent package documentation.

FAQ