cloudflare-browser-rendering

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.50.0, @cloudflare/workers-types@4.20251125.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 using it for testing.

Puppeteer API Reference

Core classes for browser automation:

1. Core Functions - launch(), connect(), sessions(), history(), limits()
2. Browser API - newPage(), sessionId(), close(), disconnect(), createBrowserContext()
3. Page API - 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 API Reference

Playwright provides a similar API to Puppeteer with slight differences.

Installation

bun add @cloudflare/playwright

Basic Example

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

Key Differences from Puppeteer

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

Session Management

Browser sessions are managed using Durable Objects for state persistence across multiple requests. Sessions support hibernation, automatic cleanup, and concurrent connection handling.

Key Patterns:

• Session Reuse - Use puppeteer.sessions() and puppeteer.connect() to reuse browsers
• Browser Contexts - Isolate cookies/cache while sharing browser instance
• Multiple Tabs - Use tabs (newPage()) instead of multiple browsers for batch operations
• Disconnect vs Close - Use disconnect() to keep session alive, close() to terminate

Load references/session-management.md for complete session lifecycle management, hibernation patterns, connection pooling strategies, and production examples.

Common Patterns

6 production-ready browser automation patterns:

1. Screenshot with KV Caching - Cache screenshots for high-traffic URLs, reduce browser usage
2. PDF Generation from HTML - Convert custom HTML to PDF for invoices, reports,