Puppeteer

Puppeteer needs two pieces: --proxy-server at launch, plus page.authenticate() for credentials.

Basic setup

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://gate.helodata.io:7777"],
});
const page = await browser.newPage();

await page.authenticate({
  username: "helo_s1a2b3c4d5e-type-res-region-us",
  password: "PASSWORD",
});

await page.goto("https://ipv4.icanhazip.com");
console.log(await page.content());
await browser.close();

page.authenticate() handles the proxy-auth dialog transparently.

ISP

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://198.51.100.42:8000"],
});
await page.authenticate({ username: "helo_s1a2b3c4d5e", password: "PASSWORD" });

Per-page proxy via puppeteer-extra-plugin-proxy

The official Puppeteer can't change proxy mid-session — once Chromium launches with --proxy-server, that's it. To rotate per-page, use the puppeteer-page-proxy plugin:

npm i puppeteer-extra puppeteer-extra-plugin-stealth puppeteer-page-proxy

import puppeteer from "puppeteer-extra";
import StealthPlugin from "puppeteer-extra-plugin-stealth";
import useProxy from "puppeteer-page-proxy";

puppeteer.use(StealthPlugin());
const browser = await puppeteer.launch();
const page = await browser.newPage();

await useProxy(page, "http://helo_s1a2b3c4d5e-type-res-region-us:[e-mail]:7777");
await page.goto("https://ipv4.icanhazip.com");

useProxy() can be called repeatedly to switch the page's proxy between requests.

ISP rotation example

import fs from "node:fs";
const list = fs.readFileSync("isp.txt", "utf8").trim().split("\n");
let i = 0;

async function fetchOne(url) {
  const line = list[i++ % list.length];
  const [ip, port, user, pass] = line.split(":");
  const p = `http://${user}:${pass}@${ip}:${port}`;
  await useProxy(page, p);
  await page.goto(url);
}

Verify

const ip = await page.evaluate(() =>
  fetch("https://ipv4.icanhazip.com").then(r => r.text())
);
console.log(ip.trim());

Common pitfalls

• page.authenticate() not set before page.goto() — the first request will block on the auth dialog. Always call authenticate() immediately after newPage().
• puppeteer-extra-plugin-stealth masks the browser fingerprint but does NOT change IP — combine with helodata for full coverage.
• Same proxy across all pages when using --proxy-server alone — for per-page proxies use the plugin above.