Overview

Puppeteer is a Node.js library that controls headless Chrome or Chromium. When scraping at scale, routing requests through proxies is essential to avoid IP bans and access geo-restricted content. This tutorial shows how to configure ProxyScrape residential and datacenter proxies in Puppeteer for both HTTP and SOCKS5 protocols. Because Chromium does not support authenticated SOCKS5 proxies directly, you will also learn how to set up a local relay using gost to bridge HTTP authentication to SOCKS5.

Prerequisites

Node.js 18 or later installed on Windows, macOS, or Linux.
A ProxyScrape account with residential or datacenter proxies. Note your proxy host, port, username, and password from the ProxyScrape dashboard.
Basic familiarity with JavaScript and the command line.

Step 1: Set up a new Node.js project

Create a new directory and initialize a project:

mkdir puppeteer-proxyscrape && cd puppeteer-proxyscrape
npm init -y

Install Puppeteer:
```
npm install puppeteer
```
This downloads a compatible Chromium build.

Step 2: Configure an HTTP proxy with authentication

ProxyScrape HTTP proxies support username/password authentication. Puppeteer can pass proxy credentials using the page.authenticate() method.

Create a file named http-proxy.js:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    args: [
      '--proxy-server=http://proxy.proxyscrape.com:12345' // Replace with your ProxyScrape host and port
    ]
  });

  const page = await browser.newPage();

  // Replace with your ProxyScrape username and password
  await page.authenticate({
    username: 'your-username',
    password: 'your-password'
  });

  await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle2' });
  const content = await page.content();
  console.log(content);

  await browser.close();
})();

Run the script:

node http-proxy.js

The output should show the proxy IP, confirming the setup.

Step 3: Rotate HTTP proxies per request

For large scrapes, rotate the proxy for each page or request. Maintain an array of proxies and select one at random or sequentially.

const proxies = [
  { host: 'proxy1.proxyscrape.com', port: 12345, username: 'user', password: 'pass' },
  { host: 'proxy2.proxyscrape.com', port: 12345, username: 'user', password: 'pass' }
];

function getRandomProxy() {
  return proxies[Math.floor(Math.random() * proxies.length)];
}

(async () => {
  const proxy = getRandomProxy();
  const browser = await puppeteer.launch({
    args: [`--proxy-server=http://${proxy.host}:${proxy.port}`]
  });
  const page = await browser.newPage();
  await page.authenticate({ username: proxy.username, password: proxy.password });
  await page.goto('https://httpbin.org/ip');
  // ...
  await browser.close();
})();

If your ProxyScrape plan provides a rotating endpoint (a single host:port that rotates the IP per request), use that instead of managing a list.

Step 4: Use SOCKS5 proxies via a local relay

Chromium supports SOCKS5 proxies but does not support username/password authentication for them. To use ProxyScrape SOCKS5 proxies with authentication, run a local relay that accepts HTTP without auth and forwards to the authenticated SOCKS5 proxy.

Install gost (a simple proxy relay). On macOS with Homebrew:
```
brew install gost
```
On Linux, download the binary from the gost releases page. On Windows, download the .exe from the same page.
Start gost with an HTTP listener and a SOCKS5 forwarder:
```
gost -L http://:8080 -F socks5://your-username:[email protected]:1080
```
Replace the username, password, host, and port with your ProxyScrape SOCKS5 details.
Point Puppeteer to the local HTTP relay:
```
const browser = await puppeteer.launch({
  args: ['--proxy-server=http://127.0.0.1:8080']
});
```
No page.authenticate() is needed because the local relay handles authentication.
Test with the same httpbin.org/ip check.

Step 5: Verify the proxy is working

Use a reliable IP echo service to confirm the proxy is active and not leaking your real IP:

await page.goto('https://api.ipify.org?format=json');
const body = await page.evaluate(() => document.body.innerText);
console.log(JSON.parse(body).ip);

Compare the returned IP with your actual IP.

Troubleshooting

407 Proxy Authentication Required: Ensure page.authenticate() is called before page.goto(). For SOCKS5, confirm the relay credentials are correct.
ERR_PROXY_CONNECTION_FAILED: Check the proxy host and port. For SOCKS5, ensure the gost relay is running and reachable.
SSL errors: Some proxies may not support HTTPS tunneling. Use HTTP proxies for HTTPS targets, or verify that your SOCKS5 proxy supports CONNECT.
Slow responses: Residential proxies can be slower. Increase timeouts with page.setDefaultNavigationTimeout(60000).
IP not changing: If using a static proxy list, confirm rotation logic. If using a rotating endpoint, check that ProxyScrape rotation is enabled in your dashboard.

Summary

You have successfully configured ProxyScrape HTTP and SOCKS5 proxies with Puppeteer. For HTTP proxies, use --proxy-server and page.authenticate(). For SOCKS5, run a local relay with gost to handle authentication. Rotate proxies per request to distribute traffic and avoid blocks. Always verify your egress IP before launching a large scrape.