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

JavaScript Playwright Proxy

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

JavaScriptPlaywright
Install:npm install playwright
JavaScript / Playwright
const { chromium } = require("playwright");

async function run() {
  const browser = await chromium.launch({
    proxy: {
      server: "http://gate.hexproxies.com:8080",
      username: "user",
      password: "pass",
    },
  });

  const page = await browser.newPage();

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

run();

Why Playwright for Proxy Work

Playwright represents the next generation of browser automation, built by the team that originally created Puppeteer at Google and now maintained by Microsoft. Its defining advantage for proxy work is native multi-browser support: a single API controls Chromium, Firefox, and WebKit with identical proxy configuration syntax. This means you can verify that your proxy-routed traffic behaves consistently across browser engines without rewriting any code. When testing geo-restricted content through gate.hexproxies.com:8080, validating across all three browsers catches rendering discrepancies that single-browser tools miss.

Playwright's architecture was designed with modern proxy workflows in mind. Unlike Puppeteer, which requires separate `page.authenticate()` calls, Playwright accepts proxy credentials directly in the browser launch configuration. This declarative approach eliminates the timing-sensitive authentication step that causes frequent bugs in Puppeteer proxy setups. Playwright also supports per-context proxies natively, enabling you to run multiple browser sessions with different proxy IPs in a single browser instance, dramatically reducing resource consumption for parallel proxy workloads.

Configuration Patterns

Playwright's proxy configuration is the most ergonomic of any browser automation framework. Pass a `proxy` object to `browser.launch()` with `server`, `username`, and `password` fields for browser-wide proxy routing. For per-session proxy assignment, pass the proxy config to `browser.newContext()` instead, which creates an isolated session with its own cookies, storage, and proxy. This context-level isolation is ideal for running 20 parallel sessions through different sticky proxy IPs on the same Chromium instance.

Playwright's route API provides an alternative proxy-like mechanism for request modification. Use `page.route('**/*', handler)` to intercept, modify, or mock any network request before it leaves the browser. While this is not a substitute for a real proxy gateway, it is valuable for testing proxy integration code locally by simulating proxy behavior, or for blocking specific request patterns (analytics, tracking pixels) to reduce proxy bandwidth usage.

Common Pitfalls

A common mistake is confusing browser-level and context-level proxy configuration. If you set a proxy on `browser.launch()`, all contexts created from that browser inherit the proxy. But if you set a proxy on `browser.newContext()`, only that context uses the proxy. Mixing these levels can lead to some pages using the proxy and others bypassing it. Decide on your proxy scope upfront: use browser-level for uniform routing, context-level for per-session IP assignment.

Playwright auto-downloads browser binaries on first install, which can fail in restricted network environments or CI pipelines. If your build environment routes all traffic through a proxy, set the `HTTPS_PROXY` environment variable before running `npx playwright install` so the browser downloads also route through the proxy. Also pin your Playwright version to avoid unexpected browser binary updates that change fingerprinting characteristics.

Performance Optimization

Playwright's context isolation is the key to efficient parallel proxy usage. Instead of launching one browser per proxy IP (which costs 200-400MB each), launch a single browser and create multiple contexts, each configured with a different proxy or sticky session. A single Chromium instance can handle 20-30 isolated contexts with different proxies, consuming roughly 500MB total versus 6GB for 30 separate browser instances.

Use Playwright's built-in tracing and HAR recording for proxy performance analysis. Enable tracing with `context.tracing.start()` to capture detailed network timing, screenshots, and DOM snapshots for each proxied page load. Export HAR files with `page.routeFromHAR()` to replay previously captured proxy sessions offline, enabling development and testing without consuming proxy bandwidth. These diagnostic tools help you identify which proxy configurations deliver the fastest page loads for your specific target sites.

Tips

  • 1
    Playwright supports proxy config at the browser level for all pages.
  • 2
    Use context-level proxies to run multiple sessions with different IPs in parallel.
  • 3
    Combine with geo-targeting parameters for region-specific testing.

Ready to Integrate?

Get proxy credentials and start coding in minutes.

Create AccountView Pricing

Related Resources

Playwright Proxy Generator

Create a Playwright proxy configuration with authentication and rotation guidance.

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.