puppeteer-proxy-plugin

Seamless proxy integration for Puppeteer and Playwright with automatic rotation, health checking, and per-page proxy assignment.

Features

Per-page proxy assignment -- route each page or context through a different proxy
Automatic rotation -- round-robin, random, or sticky (per-domain) strategies
Health checking -- periodic checks with automatic failure tracking
Dead proxy removal -- configurable auto-removal after consecutive failures
Full auth support -- HTTP, HTTPS, SOCKS4, and SOCKS5 with username/password
Puppeteer -- uses proxy-chain for transparent proxy relay
Playwright -- leverages native per-context proxy configuration
Zero config -- sensible defaults, fully customisable

Installation

npm install puppeteer-proxy-plugin

Peer dependencies

Install the browser automation library you need (or both):

# For Puppeteer
npm install puppeteer

# For Playwright
npm install playwright

Quick Start

Puppeteer

import puppeteer from 'puppeteer';
import { PuppeteerProxyPlugin } from 'puppeteer-proxy-plugin';

const plugin = new PuppeteerProxyPlugin({
  proxies: [
    'http://user:pass@proxy1.example.com:8080',
    'http://user:pass@proxy2.example.com:8080',
  ],
  rotationStrategy: 'round-robin',
});

const browser = await plugin.launch(puppeteer, { headless: true });

// Each page gets the next proxy in rotation
const page1 = await plugin.getPage(browser);
await page1.goto('https://httpbin.org/ip');

const page2 = await plugin.getPage(browser);
await page2.goto('https://httpbin.org/ip');

await plugin.close(browser);

Playwright

import { chromium } from 'playwright';
import { PlaywrightProxyPlugin } from 'puppeteer-proxy-plugin';

const plugin = new PlaywrightProxyPlugin({
  proxies: [
    'http://user:pass@proxy1.example.com:8080',
    'http://user:pass@proxy2.example.com:8080',
  ],
  rotationStrategy: 'round-robin',
});

const browser = await plugin.launch(chromium, { headless: true });

// Each context is completely isolated with its own proxy
const { context, page } = await plugin.getContext(browser);
await page.goto('https://httpbin.org/ip');
await context.close();

await plugin.close(browser);

Rotation Strategies

Round-Robin

Cycle through proxies in sequential order. Best for even load distribution.

const plugin = new PuppeteerProxyPlugin({
  proxies: myProxies,
  rotationStrategy: 'round-robin',
});

Random

Pick a random proxy on each request. Good for unpredictable patterns.

const plugin = new PuppeteerProxyPlugin({
  proxies: myProxies,
  rotationStrategy: 'random',
});

Sticky (Per-Domain)

Pin each domain to a consistent proxy. Ideal for maintaining sessions.

const plugin = new PuppeteerProxyPlugin({
  proxies: myProxies,
  rotationStrategy: 'sticky',
});

// Same domain always routes through the same proxy
const page = await plugin.getPage(browser, { stickyKey: 'github.com' });

Switching at Runtime

const rotation = plugin.getRotation();
rotation.setStrategy('random');

Pool Management

Health Checking

The pool automatically monitors proxy health with configurable intervals.

const plugin = new PuppeteerProxyPlugin({
  proxies: myProxies,
  healthCheck: true,
  healthCheckInterval: 30000, // 30 seconds
  healthCheckTimeout: 10000,  // 10 second timeout
  maxFailures: 3,             // mark dead after 3 consecutive failures
  autoRemoveDead: true,       // remove dead proxies automatically
});

Manual Reporting

const pool = plugin.getPool();

// Report success with latency
pool.reportSuccess(proxy, 250);

// Report failure (increments failure counter)
pool.reportFailure(proxy);

// Check stats
const stats = pool.getStats();
console.log(stats);
// { total: 5, healthy: 3, degraded: 1, dead: 1, averageLatency: 180 }

Dynamic Pool Updates

const pool = plugin.getPool();

// Add proxies at runtime
pool.addProxy('http://user:pass@new-proxy.example.com:8080');

// Remove a proxy
pool.removeProxy('http://user:pass@old-proxy.example.com:8080');

Proxy URL Formats

All of these formats are supported:

host:port
user:pass@host:port
http://host:port
http://user:pass@host:port
https://user:pass@host:port
socks4://user:pass@host:port
socks5://user:pass@host:port

Or use the object format:

{
  host: '1.2.3.4',
  port: 8080,
  protocol: 'http',
  username: 'user',
  password: 'pass',
  label: 'US East',
  country: 'US',
}

API Reference

Classes

Class	Description
`PuppeteerProxyPlugin`	Puppeteer integration with proxy-chain relay for per-page proxies
`PlaywrightProxyPlugin`	Playwright integration using native per-context proxy support
`ProxyPool`	Managed proxy pool with health checking and failure tracking
`RotationEngine`	Proxy selection engine with pluggable strategies