A Playwright proxy in Node.js is far less painful than in most browser tools, because Playwright accepts a username and password directly and answers the proxy's 407 challenge for you. The main decision is where you set the proxy: once for the whole browser, or separately for each browser context. That choice decides whether you can run ten isolated sessions with ten different IPs from a single browser process.
Install and First Test
npm init -y
npm install playwright
npx playwright install chromiumThen confirm the proxy works before writing anything bigger:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({
proxy: {
server: 'http://global.nodeproxies.xyz:8080',
username: 'USERNAME-country-us',
password: 'PASSWORD'
}
});
const page = await browser.newPage();
await page.goto('https://api.ipify.org');
console.log(await page.textContent('body'));
await browser.close();
})();Note that credentials go in separate fields, not inside the server URL. Putting user:pass@ in server is a common cause of silent failures.
Launch-Level vs Context-Level Proxies
A proxy set in chromium.launch() applies to every page and context in that browser. A proxy set in browser.newContext() applies only to that context, which has its own cookies, storage and cache. Context-level proxies are what you want for parallel, isolated sessions:
const { chromium } = require('playwright');
function proxyFor(sessionId) {
return {
server: 'http://global.nodeproxies.xyz:8080',
username: 'USERNAME-country-us-session-' + sessionId + '-time-10',
password: 'PASSWORD'
};
}
(async () => {
const browser = await chromium.launch();
const ids = ['a1', 'b2', 'c3'];
await Promise.all(ids.map(async (id) => {
const context = await browser.newContext({ proxy: proxyFor(id) });
const page = await context.newPage();
await page.goto('https://api.ipify.org');
console.log(id, await page.textContent('body'));
await context.close();
}));
await browser.close();
})();Each context prints a different IP, and every request inside one context keeps the same IP for up to ten minutes because they share a session id. Older Chromium versions on Windows needed a placeholder launch proxy for per-context proxies to work; current Playwright versions no longer require it, but if you're pinned to an old release and see an error about a global proxy, pass proxy: { server: 'http://per-context' } to launch().
Choosing Session Length
- Single-page fetches: rotating (no session) is fine, but sub-resources may come from different IPs. Most sites don't care; a few do.
- Logins and multi-step flows: use a sticky session longer than the flow, for example time-15 for a 5-minute checkout test.
- Long crawls in one context: rotate the session id every N pages by closing the context and opening a new one.
The trade-offs are explained with examples in rotating vs sticky proxies.
Saving Bandwidth in Playwright
Proxy traffic is billed per GB, and a modern page can weigh several megabytes, mostly images, fonts and video. If you only need the HTML or data, block heavy resources at the context level:
await context.route('**/*', (route) => {
const type = route.request().resourceType();
if (['image', 'media', 'font'].includes(type)) return route.abort();
return route.continue();
});On image-heavy sites this often cuts transfer by more than half. More tactics are in the headless browser proxies guide.
SOCKS5 in Playwright
Playwright accepts socks5:// servers, but Chromium doesn't support SOCKS5 with a username and password. For authenticated proxies, stick with the HTTP endpoint. It tunnels HTTPS with CONNECT, so your traffic is still encrypted end to end. See SOCKS5 vs HTTP proxies for when the difference matters.
Common Errors
- net::ERR_PROXY_CONNECTION_FAILED: wrong host or port, or a firewall blocking outbound 8080.
- 407 in the response or net::ERR_INVALID_AUTH_CREDENTIALS: check username and password, and that your plan is active.
- 402 from the gateway: the plan has run out of bandwidth.
- net::ERR_TUNNEL_CONNECTION_FAILED: the proxy couldn't reach the target through that IP. Open a new context with a new session id and retry.
- Timeouts: residential IPs are slower than your home connection. Raise page.setDefaultNavigationTimeout to 60 seconds.
Keep Credentials Out of Your Code
Hard-coded passwords end up in Git history and screenshots. Read them from the environment instead, and fail early if they're missing:
const PROXY_USER = process.env.PROXY_USER;
const PROXY_PASS = process.env.PROXY_PASS;
if (!PROXY_USER || !PROXY_PASS) {
throw new Error('Set PROXY_USER and PROXY_PASS');
}
const proxy = {
server: 'http://global.nodeproxies.xyz:8080',
username: PROXY_USER + '-country-us',
password: PROXY_PASS
};Run it with PROXY_USER=yourname PROXY_PASS=secret node scrape.js, or load a .env file that's listed in .gitignore. Appending options like -country-us in code keeps the base username in one place.
Running Playwright Through NodeProxies
Use http://global.nodeproxies.xyz:8080 as the server and build usernames with country and session options. The proxy username builder generates the exact string. Rotating residential proxies start at $0.65/GB with pay-as-you-go billing and balance that never expires. Sign up here and generate credentials from the dashboard.
FAQ
How do I set a different proxy for each page in Playwright?
Proxies are set per browser or per context, not per page. Create one context per IP you need and open pages inside it.
Does Playwright support proxy authentication?
Yes. Pass username and password in the proxy object at launch or context creation, and Playwright answers the 407 challenge automatically.
Does the Playwright proxy work with Firefox and WebKit?
Yes, the same proxy option works for all three browsers Playwright ships, including per-context proxies.
Why does my Playwright proxy work for HTTP but not HTTPS sites?
Usually the target refused the tunnel or timed out. Retry with a new session, and confirm the proxy itself works with curl first.
