Cloudflare Browser Rendering with Puppeteer/Playwright. Use for screenshots, PDFs, web scraping, or encountering rendering errors, timeout issues, memory exceeded.
name: cloudflare-browser-rendering description: Cloudflare Browser Rendering with Puppeteer/Playwright. Use for screenshots, PDFs, web scraping, or encountering rendering errors, timeout issues, memory exceeded.
Production-ready knowledge domain for building browser automation workflows with Cloudflare Browser Rendering.
Status: Production Ready ✅ Last Updated: 2025-11-25 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.0.0, wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0
wrangler.jsonc:
{
"name": "browser-worker",
"main": "src/index.ts",
"compatibility_date": "2023-03-14",
"compatibility_flags": ["nodejs_compat"],
"browser": {
"binding": "MYBROWSER"
}
}
Why nodejs_compat? Browser Rendering requires Node.js APIs and polyfills.
bun add @cloudflare/puppeteer
import puppeteer from "@cloudflare/puppeteer";
interface Env {
MYBROWSER: Fetcher;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const { searchParams } = new URL(request.url);
const url = searchParams.get("url") || "https://example.com";
// Launch browser
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
// Navigate and capture
await page.goto(url);
const screenshot = await page.screenshot();
// Clean up
await browser.close();
return new Response(screenshot, {
headers: { "content-type": "image/png" }
});
}
};
bunx wrangler deploy
Test at: https://your-worker.workers.dev/?url=https://example.com
CRITICAL:
env.MYBROWSER to puppeteer.launch() (not undefined)browser.close() when done (or use browser.disconnect() for session reuse)nodejs_compat compatibility flagLoad immediately when user mentions:
puppeteer-api.md → "API reference", "Puppeteer methods", "Browser class", "Page methods", "complete API"patterns.md → "examples", "how to", "screenshot", "PDF", "scraping", "automation", "form filling"session-management.md → "sessions", "hibernation", "connection pooling", "state management", "Durable Objects"pricing-and-limits.md → "cost", "pricing", "limits", "quotas", "billing", "rate limits"common-errors.md → errors, debugging, "not working", troubleshooting, "issue #4", "issue #5", "issue #6"puppeteer-vs-playwright.md → "Playwright", "comparison", "which library", "differences"Load proactively when:
patterns.mdcommon-errors.mdpricing-and-limits.mdsession-management.mdpuppeteer-api.mdCloudflare Browser Rendering provides headless Chromium browsers running on Cloudflare's global network. Use familiar tools like Puppeteer and Playwright to automate browser tasks:
| Method | Best For | Complexity |
|---|---|---|
| Workers Bindings | Complex automation, custom workflows, session management | Advanced |
| REST API | Simple screenshot/PDF tasks | Simple |
This skill covers Workers Bindings (the advanced method with full Puppeteer/Playwright APIs).
| Feature | Puppeteer | Playwright |
|---|---|---|
| API Familiarity | Most popular | Growing adoption |
| Package | @cloudflare/puppeteer@1.0.4 |
@cloudflare/playwright@1.0.0 |
| Session Management | ✅ Advanced APIs | ⚠️ Basic |
| Browser Support | Chromium only | Chromium only (Firefox/Safari not yet supported) |
| Best For | Screenshots, PDFs, scraping | Testing, frontend automation |
Recommendation: Use Puppeteer for most use cases. Playwright is ideal if you're already using it for testing.
Core classes for browser automation:
launch(), connect(), sessions(), history(), limits()newPage(), sessionId(), close(), disconnect(), createBrowserContext()goto(), screenshot(), pdf(), content(), setContent(), evaluate(), waitForSelector(), type(), click()Quick Example:
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto("https://example.com");
const screenshot = await page.screenshot({ fullPage: true });
await browser.close();
Load references/puppeteer-api.md when implementing browser automation, scraping, debugging Puppeteer-specific issues, or needing complete API signatures and method details.
Playwright provides a similar API to Puppeteer with slight differences.
bun add @cloudflare/playwright
import { env } from "cloudflare:test";
import { chromium } from "@cloudflare/playwright";
interface Env {
BROWSER: Fetcher;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const browser = await chromium.launch(env.BROWSER);
const page = await browser.newPage();
await page.goto("https://example.com");
const screenshot = await page.screenshot();
await browser.close();
return new Response(screenshot, {
headers: { "content-type": "image/png" }
});
}
};
| Feature | Puppeteer | Playwright |
|---|---|---|
| Import | import puppeteer from "@cloudflare/puppeteer" |
import { chromium } from "@cloudflare/playwright" |
| Launch | puppeteer.launch(env.MYBROWSER) |
chromium.launch(env.BROWSER) |
| Session API | ✅ Advanced (sessions, history, limits) | ⚠️ Basic |
| Auto-waiting | Manual waitForSelector() |
Built-in auto-waiting |
| Selectors | CSS only | CSS, text, XPath (via evaluate workaround) |
Recommendation: Stick with Puppeteer unless you have existing Playwright tests to migrate.
Browser sessions are managed using Durable Objects for state persistence across multiple requests. Sessions support hibernation, automatic cleanup, and concurrent connection handling.
Key Patterns:
puppeteer.sessions() and puppeteer.connect() to reuse browsersnewPage()) instead of multiple browsers for batch operationsdisconnect() to keep session alive, close() to terminateLoad references/session-management.md for complete session lifecycle management, hibernation patterns, connection pooling strategies, and production examples.
6 production-ready browser automation patterns:
Quick Example (Screenshot with caching):
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto(url);
const screenshot = await page.screenshot({ fullPage: true });
await env.CACHE.put(url, screenshot, { expirationTtl: 86400 });
await browser.close();
Load references/patterns.md when implementing browser automation patterns, scraping, PDF generation, or needing complete production examples with error handling and optimizations.
Browser Rendering charges based on CPU time (paid plans only). Free tier: 10 minutes/day. Paid tier: 10 hours/month included, then $0.09 per browser hour + $2.00 per concurrent browser above 10.
Load references/pricing-and-limits.md for complete pricing tiers, quota details, rate limiting strategies, and cost optimization techniques.
This skill prevents 6 documented issues. Top 3 critical errors detailed below:
Error: "XPath selector not supported" or selector failures
Source: https://developers.cloudflare.com/browser-rendering/faq/#why-cant-i-use-an-xpath-selector-when-using-browser-rendering-with-puppeteer
Why It Happens: XPath poses a security risk to Workers
Prevention: Use CSS selectors or page.evaluate() with XPathEvaluator
Solution:
// ❌ Don't use XPath directly (not supported)
// await page.$x('/html/body/div/h1')
// ✅ Use CSS selector
const heading = await page.$("div > h1");
// ✅ Or use XPath in page.evaluate()
const innerHtml = await page.evaluate(() => {
return new XPathEvaluator()
.createExpression("/html/body/div/h1")
.evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
.singleNodeValue.innerHTML;
});
Error: "Cannot read properties of undefined (reading 'fetch')"
Source: https://developers.cloudflare.com/browser-rendering/faq/#cannot-read-properties-of-undefined-reading-fetch
Why It Happens: puppeteer.launch() called without browser binding
Prevention: Always pass env.MYBROWSER to launch
Solution:
// ❌ Missing browser binding
const browser = await puppeteer.launch(); // Error!
// ✅ Pass binding
const browser = await puppeteer.launch(env.MYBROWSER);
Error: Browser closes unexpectedly after 60 seconds
Source: https://developers.cloudflare.com/browser-rendering/platform/limits/#note-on-browser-timeout
Why It Happens: Default timeout is 60 seconds of inactivity
Prevention: Use keep_alive option to extend up to 10 minutes
Solution:
// Extend timeout to 5 minutes for long-running tasks
const browser = await puppeteer.launch(env.MYBROWSER, {
keep_alive: 300000 // 5 minutes = 300,000 ms
});
Note: Browser closes if no devtools commands for the specified duration.
Load references/common-errors.md for complete error catalog including:
Plus solutions for page crashes, authentication issues, resource loading errors, and debugging strategies.
Critical Items Before Deployment:
nodejs_compat flag configuredLoad references/patterns.md for production-ready templates with complete error handling, monitoring, and security patterns.
Required: @cloudflare/puppeteer@1.0.4, wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0
Related Skills: cloudflare-worker-base (Worker setup), cloudflare-kv (caching), cloudflare-workers-ai (AI scraping)
{
"dependencies": {
"@cloudflare/puppeteer": "^1.0.4"
},
"devDependencies": {
"@cloudflare/workers-types": "^4.20251125.0",
"wrangler": "^4.50.0"
}
}
Alternative (Playwright):
{
"dependencies": {
"@cloudflare/playwright": "^1.0.0"
}
}
Solution: Pass browser binding to puppeteer.launch():
const browser = await puppeteer.launch(env.MYBROWSER); // Not just puppeteer.launch()
Solution: Use CSS selectors or page.evaluate() with XPathEvaluator (see Issue #1)
Solution: Extend timeout with keep_alive:
const browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 300000 });
Solution: Reuse sessions, use tabs, check limits before launching (see Issue #4)
Solution: Enable remote binding in wrangler.jsonc:
{ "browser": { "binding": "MYBROWSER", "remote": true } }
Solution: Cannot bypass. If your own zone, create WAF skip rule (see Issue #6)
Questions? Issues?
references/common-errors.md for detailed solutionsreferences/session-management.md for performance optimizationnodejs_compat compatibility flag is enabled