secondsky/claude-skills / plugins/cloudflare-browser-rendering/skills/cloudflare-browser-rendering
cloudflare-browser-rendering
VerifiedCloudflare Browser Rendering with Puppeteer/Playwright. Use for screenshots, PDFs, web scraping, or encountering rendering errors, timeout issues, memory exceeded.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.7 KB |
| references/common-errors.md | markdown | 14.9 KB |
| references/patterns.md | markdown | 12.6 KB |
| references/pricing-and-limits.md | markdown | 13.9 KB |
| references/puppeteer-api.md | markdown | 11.8 KB |
| references/puppeteer-vs-playwright.md | markdown | 15.1 KB |
| references/session-management.md | markdown | 16.4 KB |
| scripts/check-versions.shexecutable | script | 1.2 KB |
| templates/ai-enhanced-scraper.ts | script | 3.7 KB |
| templates/basic-screenshot.ts | script | 1.8 KB |
| templates/pdf-generation.ts | script | 2.8 KB |
| templates/playwright-example.ts | script | 2.7 KB |
| templates/screenshot-with-kv-cache.ts | script | 2.7 KB |
| templates/session-reuse.ts | script | 3.5 KB |
| templates/web-scraper-basic.ts | script | 2.9 KB |
| templates/web-scraper-batch.ts | script | 3.1 KB |
| templates/wrangler-browser-config.jsonc | other | 3.1 KB |
references/puppeteer-api.md
View on GitHub# Puppeteer API Reference - Cloudflare Browser Rendering
Complete API reference for Puppeteer in Cloudflare Workers Browser Rendering.
## Table of Contents
### Core Functions
- [puppeteer.launch()](#puppeteerlaunch) - Launch new browser instance
- [puppeteer.connect()](#puppeteerconnect) - Connect to existing session
- [puppeteer.sessions()](#puppeteersessions) - List running sessions
- [puppeteer.history()](#puppeteerhistory) - List recent sessions
- [puppeteer.limits()](#puppeteerlimits) - Check account limits
### Browser API
- [browser.newPage()](#browsernewpage) - Create new page/tab
- [browser.sessionId()](#browsersessionid) - Get session ID
- [browser.close()](#browserclose) - Close browser
- [browser.disconnect()](#browserdisconnect) - Disconnect without closing
- [browser.createBrowserContext()](#browsercreatebrowsercontext) - Create isolated context
### Page API
- [page.goto()](#pagegoto) - Navigate to URL
- [page.screenshot()](#pagescreenshot) - Capture screenshot
- [page.pdf()](#pagepdf) - Generate PDF
- [page.content()](#pagecontent) - Get HTML content
- [page.setContent()](#pagesetcontent) - Set custom HTML
- [page.evaluate()](#pageevaluate) - Execute JavaScript
- [page.waitForSelector()](#pagewaitforselector) - Wait for element
- [page.type()](#pagetype) - Type text into input
- [page.click()](#pageclick) - Click element
---
## Core Functions
### puppeteer.launch()
Launch a new browser instance.
**Signature:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
const sessionId = "478f4d7d-e943-40f6-a414-837d3736a1dc";
const browser = await puppeteer.connect(env.MYBROWSER, sessionId);
```
---
### puppeteer.sessions()
List currently running browser sessions.
**Signature:**
```typescript
await puppeteer.sessions(binding: Fetcher): Promise<SessionInfo[]>
```
**Returns:**
```typescript
interface SessionInfo {
sessionId: string;
startTime: number;
connectionId?: string; // Present if worker is connected
connectionStartTime?: number;
}
```
**Example:**
```typescript
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:**
```typescript
await puppeteer.history(binding: Fetcher): Promise<HistoryEntry[]>
```
**Returns:**
```typescript
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:**
```typescript
await puppeteer.limits(binding: Fetcher): Promise<LimitsInfo>
```
**Returns:**
```typescript
interface LimitsInfo {
activeSessions: Array<{ id: string }>;
maxConcurrentSessions: number;
allowedBrowserAcquisitions: number;
timeUntilNextAllowedBrowserAcquisition: number; // milliseconds
}
```
**Example:**
```typescript
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:**
```typescript
await browser.newPage(): Promise<Page>
```
**Example:**
```typescript
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:**
```typescript
const sessionId = browser.sessionId();
console.log("Current session:", sessionId);
```
---
### browser.close()
Close the browser and terminate the session.
**Signature:**
```typescript
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:**
```typescript
await browser.disconnect(): Promise<void>
```
**When to use:** Session reuse - allows another Worker to connect to the same session later.
**Example:**
```typescript
// 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:**
```typescript
await browser.createBrowserContext(): Promise<BrowserContext>
```
**Use Cases:**
- Isolate cookies and cache between operations
- Test multi-user scenarios
- Maintain session isolation while reusing browser
**Example:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
// 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:**
```typescript
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:**
```typescript
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:**
```typescript
await page.content(): Promise<string>
```
**Example:**
```typescript
const html = await page.content();
console.log(html); // Full HTML source
```
---
### page.setContent()
Set custom HTML content.
**Signature:**
```typescript
await page.setContent(html: string, options?: NavigationOptions): Promise<void>
```
**Use Case:** Generate PDFs from custom HTML.
**Example:**
```typescript
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:**
```typescript
await page.evaluate<T>(fn: () => T): Promise<T>
```
**Use Cases:**
- Extract data from the DOM
- Manipulate page content
- Workaround for XPath (not directly supported)
**Examples:**
```typescript
// Extract text content
const title = await page.evaluate(() => document.title);
// Extract structured data
const data = await page.evaluate(() => ({
title: document.title,
url: window.location.href,
headings: Array.from(document.querySelectorAll("h1, h2")).map(el => el.textContent),
links: Array.from(document.querySelectorAll("a")).map(el => el.href)
}));
// XPath workaround (XPath selectors not directly supported)
const innerHtml = await page.evaluate(() => {
return new XPathEvaluator()
.createExpression("/html/body/div/h1")
.evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE)
.singleNodeValue.innerHTML;
});
```
---
### page.waitForSelector()
Wait for an element to appear in the DOM.
**Signature:**
```typescript
await page.waitForSelector(selector: string, options?: WaitForOptions): Promise<ElementHandle>
```
**Options:**
- `timeout` (number) - Maximum wait time in milliseconds
- `visible` (boolean) - Wait for element to be visible
**Example:**
```typescript
await page.goto("https://example.com");
await page.waitForSelector("#content", { visible: true });
const screenshot = await page.screenshot();
```
---
### page.type()
Type text into an input field.
**Signature:**
```typescript
await page.type(selector: string, text: string): Promise<void>
```
**Example:**
```typescript
await page.type('input[name="email"]', 'user@example.com');
```
---
### page.click()
Click an element.
**Signature:**
```typescript
await page.click(selector: string): Promise<void>
```
**Example:**
```typescript
await page.click('button[type="submit"]');
await page.waitForNavigation();
```
---
## Best Practices
### Performance Optimization
- **Reuse browser instances** with `disconnect()` instead of `close()`
- **Use browser contexts** for isolated sessions within same browser
- **Set appropriate `keep_alive`** to balance resource usage and startup time
- **Check limits** before launching to avoid rate limiting
### Error Handling
- **Always pass browser binding** (`env.MYBROWSER`) to avoid undefined errors
- **Set reasonable timeouts** for navigation and selector waits
- **Handle navigation failures** gracefully
- **Monitor session limits** using `puppeteer.limits()`
### Resource Management
- **Close pages** when done to free memory
- **Disconnect vs close** - Use disconnect() for session reuse, close() to terminate
- **Monitor active sessions** using `puppeteer.sessions()`
- **Clean up stale sessions** periodically
---
**Last Updated**: 2025-11-25
**Cloudflare Docs**: https://developers.cloudflare.com/browser-rendering/
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |