/cloudflare-browser-rendering

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."
license: MIT
metadata:
  version: "1.0.0"
  last_verified: "2025-11-27"
  puppeteer_version: "1.0.4"
  playwright_version: "1.0.0"
  workers_types_version: "4.20260408.0"
  wrangler_version: "4.81.0"
  production_tested: true
  errors_prevented: 6
  references_included: 6
  keywords:
    - browser rendering cloudflare
    - "@cloudflare/puppeteer"
    - "@cloudflare/playwright"
    - puppeteer workers
    - playwright workers
    - screenshot cloudflare
    - pdf generation workers
    - web scraping cloudflare
    - headless chrome workers
    - browser automation
    - puppeteer.launch
    - playwright.chromium.launch
    - browser binding
    - session management
    - puppeteer.sessions
    - puppeteer.connect
    - browser.close
    - browser.disconnect
    - XPath not supported
    - browser timeout
    - concurrency limit
    - keep_alive
    - page.screenshot
    - page.pdf
    - page.goto
    - page.evaluate
    - incognito context
    - session reuse
    - batch scraping
    - crawling websites

Cloudflare Browser Rendering - Complete Reference

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.81.0, @cloudflare/workers-types@4.20260408.0

---

Table of Contents

1. [Quick Start (5 minutes)](#quick-start-5-minutes) 2. [Browser Rendering Overview](#browser-rendering-overview) 3. [Puppeteer API Reference](#puppeteer-api-reference) 4. [Playwright API Reference](#playwright-api-reference) 5. [Session Management](#session-management) 6. [Common Patterns](#common-patterns) 7. [Pricing & Limits](#pricing--limits) 8. [Known Issues Prevention](#known-issues-prevention) 9. [Production Checklist](#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

bun add @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

bunx 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

---

When to Load References

**Load 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**:

• Building new automation → Load `patterns.md`
• Debugging errors → Load `common-errors.md`
• Optimizing costs → Load `pricing-and-limits.md`
• Managing sessions → Load `session-management.md`
• Need complete API → Load `puppeteer-api.md`

---

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/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 us