Puppeteer Proxy Setup

Puppeteer is Google's Node.js library for controlling headless Chrome and Chromium browsers. It is widely used for web scraping, screenshot generation, PDF creation, and automated testing. Puppeteer supports proxy configuration through Chrome launch arguments, making it simple to route all browser traffic through Hex Proxies.

Why Use Proxies with Puppeteer?

Without proxies, Puppeteer scripts expose your server's IP to every target site. Anti-bot systems like Cloudflare, DataDome, and PerimeterX fingerprint and block repeated requests from the same IP. Residential proxies make each browser session appear as a different user from a different location, dramatically improving success rates on protected sites.

Basic Proxy Configuration

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

const page = await browser.newPage();

// Authenticate with Hex Proxies credentials await page.authenticate({ username: 'your-hex-username', password: 'your-hex-password', });

await page.goto('https://httpbin.org/ip'); console.log(await page.content()); await browser.close(); ```

IP Whitelist Authentication

If you whitelist your server IP in the Hex Proxies dashboard, skip the `page.authenticate` step — requests are authorized by source IP automatically.

Geo-Targeted Requests

Append country or city codes to your username for geographic targeting:

await page.authenticate({
  username: 'your-hex-username-country-gb-city-london',
  password: 'your-hex-password',
});

Best Practices

• **Pair proxy rotation with user-agent rotation** to create realistic browser fingerprints.
• **Use sticky sessions** for login-heavy workflows, checkout flows, and any multi-page navigation that requires session persistence.
• **Set realistic viewport sizes** and enable JavaScript to avoid headless browser detection.
• **Add request delays** between navigations to mimic human browsing patterns.

Troubleshooting

• **403 or blocked responses**: Reduce request frequency, rotate user agents, and use residential proxies instead of datacenter IPs.
• **Authentication popup**: Ensure `page.authenticate` is called before `page.goto`. Puppeteer does not support inline credentials in the proxy URL.
• **Memory leaks**: Close browser instances after each task. Use `browser.close()` in a finally block.
• **Slow page loads**: Residential proxies add 1-3 seconds of latency. Increase navigation timeouts with `page.setDefaultNavigationTimeout(60000)`.