How to Configure Node Fetch Proxy: Agent, Auth, and Checks

Create a ProxyAgent

import { ProxyAgent } from "undici";
const proxyUrl = new URL("http://HOST:PORT");
const dispatcher = new ProxyAgent({ uri: proxyUrl.origin });

Use placeholders in shared examples. Construct the real endpoint at runtime from protected configuration.

Confirm the installed Node.js and Undici versions before copying an example. Runtime behavior and supported options can change, so the tested version belongs in the record.

Use dispatcher for one request

const response = await fetch("https://TARGET.EXAMPLE", {
  dispatcher,
  signal: AbortSignal.timeout(15000),
});
if (!response.ok) throw new Error(
HTTP ${response.status}
);

A request-scoped dispatcher limits the setting to this call. Reserve process-wide configuration for applications that deliberately need one shared network path.

Use AbortSignal.timeout or an equivalent explicit cancellation path. A timeout should stop the request and preserve enough redacted context to identify the stage that failed.

Add authentication safely

const raw = process.env.PROXY_USER + ":" + process.env.PROXY_PASSWORD;
const token = "Basic " + Buffer.from(raw).toString("base64");
const dispatcher = new ProxyAgent({ uri: "http://HOST:PORT", token });

Keep environment values outside committed files and never print the token or assembled proxy URL. A 407 response should trigger an authentication-format check, not broader retries.

Construct authentication only after protected values are loaded. Validation errors should name the missing field rather than print the assembled token or proxy URL.

Before choosing, confirm whether this task needs a continuous review window or several independent samples.

Static residential addresses serve continuity. Dynamic residential addresses serve independent samples. Neither should be presented as an outcome guarantee.

For more detail, see the static residential proxy guide, the dynamic residential proxy guide, and current IPIPD pricing.

Use the official Node.js fetch documentation to verify command and parameter behavior.

After the check: Verify, diagnose, and roll back

Request a permitted diagnostic endpoint and record HTTP status, elapsed time, endpoint label, and expected exit result. Diagnose refusal, timeout, DNS, and TLS failures separately. Close the dispatcher and restore the previous path before changing another variable.

Examples are limited to authorized public-page checks and connection testing. IPIPD product wording is limited to static residential addresses and dynamic residential addresses; no access, account, or platform outcome is promised.

Pair exit verification with one permitted target request. A successful diagnostic response proves only that test path, not that every target or platform will return the same result.

Handoff Record for the Node.js Fetch Configuration

The handoff should preserve Node.js and Undici versions, proxy scheme, dispatcher scope, timeout, target host, status, timing, and rollback method. Source and logs must contain redacted fields only, never usernames, passwords, or a complete authentication token.

The reviewer should confirm whether the request uses a request-scoped dispatcher or a process-wide global dispatcher. For 407, refusal, DNS, TLS, or timeout failures, change one field and repeat against the same authorized target.

A continuous review can preserve one static residential address condition, while independent public-page samples can use separately labeled dynamic residential addresses. Close the agent and restore the original path when the task ends instead of widening the request scope.

Before testing a global dispatcher, inventory every module in the same process that may initiate network traffic. A process-wide setting can affect health checks, telemetry, dependency lookups, or background requests that were not part of the original test. Use it only when that wider effect is intentional, save the previous dispatcher, restore it after the test, and repeat one direct baseline request to confirm that rollback worked.

Separate failures from the proxy connection stage and the target response stage. A 407 response is evidence about proxy authentication. Connection refusal usually points toward host, port, protocol, or reachability. TLS errors and target HTTP status codes need their own records. Change one variable at a time and repeat the same permitted request so the final note can identify which configuration change actually altered the result.

The code review should also cover secret lifetime. HOST, PORT, username, and password in examples are dummy field names; real values should be injected by the runtime with the narrowest practical visibility. Logs can record whether a required field exists, the non-sensitive endpoint label, the response status, and a redacted result. They should not retain the token, the complete authenticated URL, environment variable values, or a raw exception that may embed those details.

Verification should use two deliberately small checks. First, call a permitted diagnostic endpoint to confirm that the dispatcher is active and capture timing. Second, call one authorized public target to distinguish transport behavior from an application-specific response. Store the two results separately, because a successful diagnostic request does not guarantee that a target will accept the request or return the expected content.