Puppeteer Proxy Examples (Node.js)

This repo contains working examples of using proxies in Puppeteer:
from static proxies to full proxy pool rotation with blacklist.
Designed for Node.js 18+, no extra frameworks.

Table of Contents

1. Requirements
2. Project Structure
3. Proxy Examples
   • Static Proxy
   • Proxy with Authentication
   • Page-level Proxy
   • Proxy Rotation
   • Proxy Rotation + User-Agent
   • Headless Evasion + Proxy
   • Monitoring Proxy Health
   • Full Proxy Pool with Blacklist

Requirements

• Node.js 18+
• npm or yarn

Install Dependencies

npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth axios

Project Structure

puppeteer-proxy-examples/
│
├── examples/
│   ├── static_proxy.js
│   ├── proxy_auth.js
│   ├── page_level_proxy.js
│   ├── proxy_rotation.js
│   ├── proxy_rotation_with_useragent.js
│   ├── headless_evasion.js
│   ├── monitoring_proxy_health.js
│   ├── proxy_pool_blacklist.js
│
└── README.md

Each script shows a different tactic for using proxies in Puppeteer. Run any script with:

node examples/static_proxy.js

---

Proxy Examples

Static Proxy

Use a single static proxy for all requests.

Parameter	Description	Example
--proxy-server	Puppeteer CLI arg for proxy	http://127.0.0.1:8000

Proxy with Authentication

Handle proxies requiring username/password.

Parameter	Description	Example
username	Proxy username	'user'
password	Proxy password	'pass'

Page-level Proxy

Apply proxy logic per request via request interception.

Proxy Rotation

Rotate through a list of proxies on each run.

Parameter	Description	Example
proxies	Array of proxies	['http://port1:host', 'http://port2:host']

Proxy Rotation + User-Agent

Rotate both proxies and User-Agents for fingerprint diversity.

Headless Evasion + Proxy

Use puppeteer-extra with stealth plugin + proxy. Helps bypass simple bot detections.

Monitoring Proxy Health

Check which proxies are alive before passing them to Puppeteer.

Full Proxy Pool with Blacklist

Rotate through a proxy pool, automatically removing bad proxies. Keeps only working proxies for stable scraping.

Disclaimer

These examples are for educational purposes only. Learn more about the legality of web scraping.

📎 More Resources

• How to Set Up Proxy in Puppeteer
• Join the community on Discord
• Star this repo if helpful ⭐