jackspace/claudeskillz/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-10-22 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: @cloudflare/puppeteer@1.0.4, @cloudflare/playwright@1.0.0, wrangler@4.43.0

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

This skill covers Workers Bindings (the advanced method with full Puppeteer/Playwright APIs).

Puppeteer vs Playwright

Recommendation: Use Puppeteer for most use cases. Playwright is ideal if you're already using it for testing.

Puppeteer API Reference

puppeteer.launch()

Launch a new browser instance.

Signature:

await puppeteer.launch(binding: Fetcher, options?: LaunchOptions): Promise<Browser>

Parameters:

• binding (required) - Browser binding from env.MYBROWSER
• options (optional):
• keep_alive (number) - Keep browser alive for N milliseconds (max: 600000 = 10 minutes)

Returns: Promise<Browser> - Browser instance

Example:

const browser = await puppeteer.launch(env.MYBROWSER, {
  keep_alive: 60000 // Keep alive for 60 seconds
});

CRITICAL: Must pass env.MYBROWSER binding. Error "Cannot read properties of undefined (reading 'fetch')" means the binding wasn't passed.

puppeteer.connect()

Connect to an existing browser session.

Signature:

await puppeteer.connect(binding: Fetcher, sessionId: string): Promise<Browser>

Use Cases:

• Reuse existing browser sessions for performance
• Share browser instance across multiple Workers
• Reduce startup time

Example:

const sessionId = "478f4d7d-e943-40f6-a414-837d3736a1dc";
const browser = await puppeteer.connect(env.MYBROWSER, sessionId);

puppeteer.sessions()

List currently running browser sessions.

Signature:

await puppeteer.sessions(binding: Fetcher): Promise<SessionInfo[]>

Returns:

interface SessionInfo {
  sessionId: string;
  startTime: number;
  connectionId?: string;  // Present if worker is connected
  connectionStartTime?: number;
}

Example:

const sessions = await puppeteer.sessions(env.MYBROWSER);
// Find sessions without active connections
const freeSessions = sessions.filter(s => !s.connectionId);

puppeteer.history()

List recent sessions (both open and closed).

Signature:

await puppeteer.history(binding: Fetcher): Promise<HistoryEntry[]>

Returns:

interface HistoryEntry {
  sessionId: string;
  startTime: number;
  endTime?: number;
  closeReason?: number;
  closeReasonText?: string; // "NormalClosure", "BrowserIdle", etc.
}

Use Case: Monitor usage patterns and debug session issues.

puppeteer.limits()

Check current account limits and available sessions.

Signature:

await puppeteer.limits(binding: Fetcher): Promise<LimitsInfo>

Returns:

interface LimitsInfo {
  activeSessions: Array<{ id: string }>;
  maxConcurrentSessions: number;
  allowedBrowserAcquisitions: number;
  timeUntilNextAllowedBrowserAcquisition: number; // milliseconds
}

Example:

const limits = await puppeteer.limits(env.MYBROWSER);
if (limits.allowedBrowserAcquisitions === 0) {
  return new Response("Rate limit reached", { status: 429 });
}

Browser API

Methods available on the Browser object returned by launch() or connect().

browser.newPage()

Create a new page (tab) in the browser.

Signature:

await browser.newPage(): Promise<Page>

Example:

const page = await browser.newPage();
await page.goto("https://example.com");

Performance Tip: Reuse browser instances and open multiple tabs instead of launching new browsers.

browser.sessionId()

Get the current browser session ID.

Returns: string - Session ID

Example:

const sessionId = browser.sessionId();
console.log("Current session:", sessionId);

browser.close()

Close the browser and terminate the session.

Signature:

await browser.close(): Promise<void>

When to use: When you're completely done with the browser and want to free resources.

browser.disconnect()

Disconnect from the browser WITHOUT closing it.

Signature:

await browser.disconnect(): Promise<void>

When to use: Session reuse - allows another Worker to connect to the same session later.

Example:

// Keep session alive for reuse
const sessionId = browser.sessionId();
await browser.disconnect(); // Don't close, just disconnect
// Later: puppeteer.connect(env.MYBROWSER, sessionId)

browser.createBrowserContext()

Create an isolated incognito browser context.

Signature:

await browser.createBrowserContext(): Promise<BrowserContext>

Use Cases:

• Isolate cookies and cache between operations
• Test multi-user scenarios
• Maintain session isolation while reusing browser

Example:

const context1 = await browser.createBrowserContext();
const context2 = await browser.createBrowserContext();
const page1 = await context1.newPage();
const page2 = await context2.newPage();
// page1 and page2 have separate cookies/cache

Page API

Methods available on the Page object returned by browser.newPage().

page.goto()

Navigate to a URL.

Signature:

await page.goto(url: string, options?: NavigationOptions): Promise<Response>

Options:

• waitUntil - When to consider navigation complete:
• "load" - Wait for load event (default)
• "domcontentloaded" - Wait for DOMContentLoaded
• "networkidle0" - Wait until no network connections for 500ms
• "networkidle2" - Wait until ≤2 network connections for 500ms
• timeout - Maximum navigation time in milliseconds (default: 30000)

Example:

await page.goto("https://example.com", {
  waitUntil: "networkidle0",
  timeout: 60000
});

Best Practice: Use "networkidle0" for dynamic content, "load" for static pages.

page.screenshot()

Capture a screenshot of the page.

Signature:

await page.screenshot(options?: ScreenshotOptions): Promise<Buffer>

Options:

• fullPage (boolean) - Capture full scrollable page (default: false)
• type (string) - "png" or "jpeg" (default: "png")
• quality (number) - JPEG quality 0-100 (only for jpeg)
• clip (object) - Capture specific region: { x, y, width, height }

Examples:

// Full page screenshot
const screenshot = await page.screenshot({ fullPage: true });
// JPEG with compression
const screenshot = await page.screenshot({
  type: "jpeg",
  quality: 80
});
// Specific region
const screenshot = await page.screenshot({
  clip: { x: 0, y: 0, width: 800, height: 600 }
});

page.pdf()

Generate a PDF of the page.

Signature:

await page.pdf(options?: PDFOptions): Promise<Buffer>

Options:

• format (string) - Page format: "Letter", "A4", etc.
• printBackground (boolean) - Include background graphics (default: false)
• margin (object) - { top, right, bottom, left } (e.g., "1cm")
• landscape (boolean) - Landscape orientation (default: false)
• scale (number) - Scale factor 0.1-2 (default: 1)

Example:

const pdf = await page.pdf({
  format: "A4",
  printBackground: true,
  margin: { top: "1cm", right: "1cm", bottom: "1cm", left: "1cm" }
});
return new Response(pdf, {
  headers: { "content-type": "application/pdf" }
});

page.content()

Get the full HTML content of the page.

Signature:

await page.content(): Promise<string>

Example:

const html = await page.content();
console.log(html); // Full HTML source

page.setContent()

Set custom HTML content.

Signature:

await page.setContent(html: string, options?: NavigationOptions): Promise<void>

Use Case: Generate PDFs from custom HTML.

Example:

await page.setContent(`
  <!DOCTYPE html>
  <html>
    <head><style>body { font-family: Arial; }</style></head>
    <body><h1>Hello World</h1></body>
  </html>
`);
const pdf = await page.pdf({ format: "A4" });

page.evaluate()

Execute JavaScript in the browser context.

Signature:

await page.evaluate<T>(fn: () => T): Promise<T>

Use Cases:

• Extract data from the DOM
• Manipulate page content
• Workaround for XPath (not directly supported)