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.
how to use cloudflare-browser-rendering
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use cloudflare-browser-rendering on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add cloudflare-browser-rendering
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/jezweb/claude-skills --skill cloudflare-browser-renderingcopy
The skills CLI fetches cloudflare-browser-rendering from GitHub repository jezweb/claude-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/cloudflare-browser-rendering
Reload or restart Cursor to activate cloudflare-browser-rendering. Access the skill through slash commands (e.g., /cloudflare-browser-rendering) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?