Use a Proxy IP with Node's Undici

Undici routes a request through a dispatcher. Create a ProxyAgent for the selected HTTP proxy and pass it on the fetch call instead of changing the global dispatcher for the entire process.

npm install [email protected]

import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent('http://203.0.113.10:8080');

try {
  const response = await fetch('https://example.com/', {
    dispatcher,
    signal: AbortSignal.timeout(15000),
  });

  console.log(response.status);
  console.log(await response.text());
} finally {
  await dispatcher.close();
}

Save the program as an .mjs file, or use an ES-module project. Replace the documentation IP with an HTTP proxy from the HTTP proxy list. The import deliberately uses Undici's fetch implementation, so the dispatcher option belongs to the client shown in the example.

Check Node compatibility before blaming the IP

Undici's supported Node versions depend on the package release. This example uses Undici 8.12.3, which requires Node 22.19.0 or newer. A module-loading or engine-version error happens before the request reaches a proxy. Check the installed package's engine requirement rather than assuming every Node release runs the newest Undici.

One agent can serve repeated requests

The short program closes its dispatcher when it finishes. If a running application sends several requests through the same endpoint, retain the agent for that workload and close it when the workload ends. Constructing and closing an agent around every URL prevents useful connection reuse.

A global dispatcher is appropriate only when you intend the broader change. Passing one explicitly makes it easier to test a proxy IP without changing another component's outgoing requests.

Look at the response and the failure stage

Fetch does not treat every HTTP error status as a rejected promise. A 403 or 429 can be a real website response carried through the proxy. A connection or tunnel error can instead reject the request before there is a response object. Read the status separately from errors thrown by the call.

If authentication is required, Undici's ProxyAgent exposes constructor-level authentication options. Do not add a proxy authorization header to the website's request headers; the agent handles a different connection hop.