v1.10.82-f67ee7d
Skip to main content
← Back to Code Snippets

JavaScript Puppeteer Proxy

Complete Puppeteer proxy integration example for JavaScript/Node.js with Hex Proxies. Includes authentication, timeouts, and error handling.

JavaScriptPuppeteer
Install:npm install puppeteer
JavaScript / Puppeteer
const puppeteer = require("puppeteer");

async function run() {
  const browser = await puppeteer.launch({
    args: ["--proxy-server=http://gate.hexproxies.com:8080"],
  });

  const page = await browser.newPage();

  await page.authenticate({
    username: "user",
    password: "pass",
  });

  try {
    await page.goto("https://httpbin.org/ip", {
      waitUntil: "domcontentloaded",
      timeout: 30000,
    });
    const body = await page.evaluate(() => document.body.innerText);
    console.log("Response:", body);
  } catch (error) {
    console.error("Navigation failed:", error.message);
  } finally {
    await browser.close();
  }
}

run();

Why Puppeteer for Proxy Work

Puppeteer provides high-level control over a headless Chrome instance through the Chrome DevTools Protocol, making it the premier tool for proxy-assisted browser automation in the JavaScript ecosystem. While raw HTTP clients handle simple request-response cycles, Puppeteer renders full web pages with JavaScript execution, CSS layouts, and network waterfalls identical to a real user's browser. This capability is essential when working with single-page applications, JavaScript-rendered content, or sites that use browser fingerprinting to detect automated traffic routed through proxies.

Google maintains Puppeteer as an official Chrome project, which guarantees compatibility with the latest Chromium releases and access to cutting-edge DevTools Protocol features. This upstream relationship means proxy-related Chrome flags and authentication mechanisms work reliably in Puppeteer before they are available in third-party automation tools. The tight coupling with Chrome also enables advanced proxy-adjacent features like network interception, request blocking, and response modification through `page.setRequestInterception()`.

Configuration Patterns

Puppeteer's proxy setup uses Chrome's `--proxy-server` launch argument to route all browser traffic through gate.hexproxies.com:8080. Authentication is handled separately through `page.authenticate()`, which must be called before any navigation on each new page. This two-step configuration pattern is necessary because Chrome's proxy argument does not support inline credentials for HTTPS proxies, unlike simple HTTP clients.

For scenarios requiring different proxies per tab, launch the browser without a proxy argument and instead use Puppeteer's request interception to route requests through different proxies programmatically. Alternatively, create multiple browser contexts with different proxy configurations using `browser.createIncognitoBrowserContext()`. Each context maintains independent cookies, cache, and proxy settings, enabling parallel sessions with different IP addresses.

Common Pitfalls

The most critical pitfall is calling `page.authenticate()` after navigation has already started. Authentication credentials must be set before the first network request on a page, which means calling it immediately after `browser.newPage()` and before any `page.goto()` or `page.setContent()`. If you forget this ordering, the first request hits the proxy without credentials, receives a 407 response, and the page load fails with a generic navigation error that does not clearly indicate an auth problem.

Resource leaks are amplified in Puppeteer proxy workflows because each browser instance runs a full Chromium process consuming 150-400MB of RAM. A script that opens browsers in a loop without proper cleanup will exhaust system memory within minutes. Implement defensive coding with try/finally blocks around all browser operations, set a maximum page lifetime timer, and monitor `process.memoryUsage().heapUsed` to detect leaks. In production, use a process manager that restarts your script if memory exceeds a threshold.

Performance Optimization

Reduce Puppeteer's proxy overhead by disabling unnecessary browser features. Pass `--disable-gpu`, `--disable-dev-shm-usage`, `--no-sandbox`, and `--disable-setuid-sandbox` as launch arguments for headless environments. Block resource types you do not need using request interception: intercepting and aborting image, font, and stylesheet requests can reduce proxied bandwidth by 60-80 percent and cut page load times in half.

Implement a browser pool to amortize the 2-3 second Chromium startup cost across many tasks. Pre-launch 5-10 browser instances, queue incoming work, assign a browser from the pool, and return it after each task completes. Combined with tab recycling (navigating to `about:blank` between tasks to clear state), this pattern lets you process hundreds of proxied pages per minute from a modest server without the per-task overhead of launching and closing browsers.

Tips

  • 1
    Use page.authenticate() for username/password proxy auth in Puppeteer.
  • 2
    Set waitUntil to domcontentloaded for faster page loads when full rendering is unnecessary.
  • 3
    Always close the browser in a finally block to prevent zombie processes.

Ready to Integrate?

Get proxy credentials and start coding in minutes.

Create AccountView Pricing

Related Resources

Puppeteer Proxy Generator

Create a Puppeteer proxy setup with authenticated routing.

Residential Proxies

High-quality residential proxies with rotating IPs from 100+ countries. Perfect for web scraping, data collection, and market research.

ISP Proxies

Ultra-fast ISP proxies with static IPs and unlimited bandwidth. Optimized for sneaker sites, social media, and high-speed tasks.

Rotating Proxies

Automatic IP rotation with every request or on a timed interval. Built for large-scale scraping and data collection.