Quick start
Use a proxy with Node.js
Route Node.js requests through a ProxyOnly proxy with undici, with retries, countries and sessions.
This guide is part of the ProxyOnly quick-start series. It assumes nothing and takes a few minutes. Prices are live, and you can start with a balance of one US dollar in any of the 63 countries we stock.
- Guide
- Use a proxy with Node.js
- Series
- 13 quick-start guides
- Minimum balance
- US$1
The minimum that works
Current Node.js versions include fetch, but the built-in version does not take a proxy setting by itself. The undici package provides a ProxyAgent that you pass as the dispatcher. The example prints the exit address.
import { ProxyAgent } from "undici";
const proxy = "http://username-country-us:[email protected]:8000";
const dispatcher = new ProxyAgent(proxy);
const res = await fetch("https://httpbin.org/ip", { dispatcher });
console.log(res.status, await res.json());Timeouts and retries
Fetch has no timeout unless you add one. Use an AbortSignal with a deadline, and wrap the call in a small retry loop with a growing pause. Without a deadline a single stalled connection can block a job indefinitely.
async function get(url, tries = 3) {
for (let i = 0; i < tries; i++) {
try {
const res = await fetch(url, { dispatcher, signal: AbortSignal.timeout(20000) });
if (res.ok) return res;
} catch {}
await new Promise((r) => setTimeout(r, 2 ** i * 1000));
}
return null;
}Country and session
Create one agent for each country and session you need, and reuse it. Making a new agent for every request throws away the connection reuse that makes things fast. Keep a small map of agents keyed by the username.
const agents = new Map();
function agent(country = "us", session) {
const user = `username-country-${country}${session ? `-session-${session}` : ""}`;
if (!agents.has(user)) {
agents.set(user, new ProxyAgent(`http://${user}:[email protected]:8000`));
}
return agents.get(user);
}Common Node.js pitfalls
Do not run thousands of requests at once. Use a small pool, for example a queue with a handful of workers, so that you do not overwhelm the target or your own machine. Read the body of every response, or cancel it, because unread bodies keep connections busy.
If you use Axios, Got or another client, the idea is the same: give it an http proxy with credentials. The integrations directory has a short example for each of them.
Which proxy type fits any country
The right type depends on how strict the destination is, how much traffic you will send and how long you need the address. A short comparison of the types we sell:
Datacenter IPv4. The default choice for most jobs. These are dedicated IPv4 addresses hosted in a datacenter, fast and inexpensive, and the best fit for high-volume reading of public pages, monitoring and automation. Some websites treat datacenter ranges more cautiously than consumer connections, so test your target before you commit to a long rental.
ISP proxies. Static addresses that are registered to an internet service provider rather than a hosting company. They keep the speed of datacenter hardware and look more like an ordinary home or office connection, which helps with destinations that are strict about hosting ranges.
Shared IPv4. A shared address is used by more than one customer and costs less. It suits light tasks, quick checks and testing where a clean, exclusive address is not essential.
IPv6. IPv6 addresses are very cheap and plentiful, and they work well with destinations that serve IPv6 traffic, such as many large search, video and social platforms. Many smaller sites are still IPv4 only, so check that your target supports IPv6 before you buy.
Mobile proxies. Addresses from mobile carrier networks. Many phones share the same carrier address, so websites tend to be tolerant of this traffic, which makes mobile proxies the right choice for testing mobile ads, apps and landing pages. They cost more than datacenter addresses.
Residential proxies. Addresses from home internet connections, billed by the amount of traffic you use and not by the IP. They suit light, bursty jobs on sites that block datacenter and ISP ranges. Heavy traffic gets expensive quickly, so estimate your monthly volume first.
If you are unsure, rent one address of the type you think you need, run your real task against it for a day, and look at the success rate. Because rental periods start at a few days, trying a type costs very little.
Using proxies responsibly in any country
A proxy is a networking tool and it is lawful in most places, but what you do with it still has to be lawful and fair. Follow the laws that apply to you and to the place you send traffic to, read the terms of the sites you visit, honour robots rules and rate limits, and never use an address to access accounts or data that are not yours. ProxyOnly cannot give legal advice, and our acceptable use policy applies to every order.
In practice that means reading public pages, checking your own sites and ads, and testing your own products. If a task would be unwelcome to the site owner when done by hand, it is unwelcome when done through a proxy too.
Frequently asked questions
Does built-in fetch support proxies?
Not by a setting. Use undici's ProxyAgent as the dispatcher.
How do I add a timeout?
Pass an AbortSignal.timeout value as the signal option.
Can I use Axios or Got instead?
Yes. Each accepts an http proxy with credentials. See the integrations directory.
How many requests should I run in parallel?
Start with a few and raise slowly while you watch the error rate.
Ready to try it?
Create an account, add funds from US$1 and pick your country and proxy type.