Cloudflare Browser Rendering - Complete Reference

Production-ready knowledge domain for building browser automation workflows with Cloudflare Browser Rendering.

Status: Production Ready ✅ Last Updated: 2026-01-21 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: @cloudflare/[email protected], @cloudflare/[email protected], [email protected]

Recent Updates (2025):

• Sept 2025: Playwright v1.55 GA, Stagehand framework support (Workers AI), /links excludeExternalLinks param
• Aug 2025: Billing GA (Aug 20), /sessions endpoint in local dev, X-Browser-Ms-Used header
• July 2025: Playwright v1.54.1 + MCP v0.0.30, Playwright local dev support ([email protected]+), Puppeteer v22.13.1 sync, /content returns title, /json custom_ai param, /screenshot viewport 1920x1080 default
• June 2025: Web Bot Auth headers auto-included
• April 2025: Playwright support launched, free tier introduced

---

Table of Contents

1. Quick Start (5 minutes)
2. Browser Rendering Overview
3. Puppeteer API Reference
4. Playwright API Reference
5. Session Management
6. Common Patterns
7. Pricing & Limits
8. Known Issues Prevention
9. Production Checklist

---

Quick Start (5 minutes)

1. Add Browser Binding

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.

2. Install Puppeteer

npm install @cloudflare/puppeteer

3. Take Your First Screenshot

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" }
    });
  }
};

4. Deploy

npx wrangler deploy

Test at: https://your-worker.workers.dev/?url=https://example.com

CRITICAL:

• Always pass env.MYBROWSER to puppeteer.launch() (not undefined)
• Always call browser.close() when done (or use browser.disconnect() for session reuse)
• Use nodejs_compat compatibility flag

---

Browser Rendering Overview

What is Browser Rendering?

Cloudflare Browser Rendering provides headless Chromium browsers running on Cloudflare's global network. Use familiar tools like Puppeteer and Playwright to automate browser tasks:

• Screenshots - Capture visual snapshots of web pages
• PDF Generation - Convert HTML/URLs to PDFs
• Web Scraping - Extract content from dynamic websites
• Testing - Automate frontend tests
• Crawling - Navigate multi-page workflows

Two Integration Methods

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).

Puppeteer vs Playwright

Feature	Puppeteer	Playwright
API Familiarity	Most popular	Growing adoption
Package	@cloudflare/[email protected]	@cloudflare/[email protected]
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.

---

Puppeteer API Reference

Core APIs (complete reference: https://pptr.dev/api/):

Global Functions:

• puppeteer.launch(env.MYBROWSER, options?) - Launch new browser (CRITICAL: must pass binding)
• puppeteer.connect(env.MYBROWSER, sessionId) - Connect to existing session
• puppeteer.sessions(env.MYBROWSER) - List running sessions
• puppeteer.history(env.MYBROWSER) - List recent sessions (open + closed)
• puppeteer.limits(env.MYBROWSER) - Check account limits

Browser Methods:

• browser.newPage() - Create new tab (preferred over launching new browsers)
• browser.sessionId() - Get session ID for reuse
• browser.close() - Terminate session
• browser.disconnect() - Keep session alive for reuse
• browser.createBrowserContext() - Isolated incognito context (separate cookies/cache)

Page Methods:

• page.goto(url, { waitUntil, timeout }) - Navigate (use "networkidle0" for dynamic content)
• page.screenshot({ fullPage, type, quality, clip }) - Capture image
• page.pdf({ format, printBackground, margin }) - Generate PDF
• page.evaluate(() => ...) - Execute JS in browser (data extraction, XPath workaround)
• page.content() / page.setContent(html) - Get/set HTML
• page.waitForSelector(selector) - Wait for element
• page.type(selector, text) / page.click(selector) - Form interaction

Critical Patterns:

// Must pass binding
const browser = await puppeteer.launch(env.MYBROWSER); // ✅
// const browser = await puppeteer.launch(); // ❌ Error!

// Session reuse for performance
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSessions = sessions.filter(s => !s.connectionId);
if (freeSessions.length > 0) {
  browser = await puppeteer.connect(env.MYBROWSER, freeSessions[0].sessionId);
}

// Keep session alive
await browser.disconnect(); // Don't close

// XPath workaround (not directly supported)
const data = await page.evaluate(() => {
  return new XPathEvaluator()
    .createExpression("/html/body/div/h1")
    .evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
    .singleNodeValue.innerHTML;
});

---

Playwright API Reference

Status: GA (Sept 2025) - Playwright v1.55, MCP v0.0.30 support, local dev support ([email protected]+)

Installation:

npm install @cloudflare/playwright

Configuration Requirements (2025 Update):

{
  "compatibility_flags": ["nodejs_compat"],
  "compatibility_date": "2025-09-15"  // Required for Playwright v1.55
}

Basic Usage:

import { chromium } from "@cloudflare/playwright";

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();

Puppeteer vs Playwright:

• Import: puppeteer vs { chromium } from "@cloudflare/playwright"
• Session API: Puppeteer has advanced session management (sessions/history/limits), Playwright basic
• Auto-waiting: Playwright has built-in auto-waiting, Puppeteer requires manual waitForSelector()
• MCP Support: Playwright MCP v0.0.30 (July 2025), Playwright MCP server available
• Latest Version: Playwright v1.57 support (Jan 2026 update)

Recommendation: Use Puppeteer for session reuse patterns. Use Playwright if migrating existing tests or need MCP integration.

Official Docs: https://developers.cloudflare.com/browser-rendering/playwright/

---

Session Management

Why: Launching new browsers is slow and consumes concurrency limits. Reuse sessions for faster response, lower concurrency usage, better resource utilization.

Session Reuse Pattern (Critical)

async function getBrowser(env: Env): Promise<Browser> {
  const sessions = await puppeteer.sessions(env.MYBROWSER);
  const freeSessions = sessions.