Guide for implementing Cloudflare Browser Rendering - a headless browser automation API for screenshots, PDFs, web scraping, and testing...
Control headless browsers with Cloudflare's Workers Browser Rendering API. Automate tasks, take screenshots, convert pages to PDFs, extract data, and test web apps.
Use Cloudflare Browser Rendering when you need to:
Quick integration using HTTP endpoints. Ideal for one-off tasks or external service integration.
Available Endpoints:
/screenshot - Capture PNG/JPEG/WebP screenshots/pdf - Generate PDF documents/content - Extract fully rendered HTML/markdown - Convert pages to Markdown/scrape - Extract data via CSS selectors/links - Extract and analyze page links/json - Extract JSON-LD, Schema.org metadata/snapshot - Debug with multi-step browser statesAuthentication:
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/screenshot" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'
Rate Limits:
Full Puppeteer API access within Cloudflare Workers for maximum control.
Setup (wrangler.toml):
name = "browser-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
browser = { binding = "MYBROWSER" }
[[kv_namespaces]]
binding = "KV"
id = "your-kv-namespace-id"
Basic Screenshot Worker:
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
const screenshot = await page.screenshot({ type: 'png' });
await browser.close();
return new Response(screenshot, {
headers: { 'Content-Type': 'image/png' },
});
},
};
Key Puppeteer Methods:
puppeteer.launch(binding) - Start new browserbrowser.newPage() - Create new pagepage.goto(url, options) - Navigate to URLpage.screenshot(options) - Capture screenshotpage.content() - Get HTML contentpage.pdf(options) - Generate PDFpage.evaluate(fn) - Execute JS in page contextbrowser.disconnect() - Disconnect keeping session alivebrowser.close() - Close and end sessionpuppeteer.connect(binding, sessionId) - Reconnect to sessionSession Reuse (Critical for Cost Optimization):
// Disconnect instead of close to keep session alive
await browser.disconnect();
// Retrieve and reconnect to existing session
const sessions = await puppeteer.sessions(env.MYBROWSER);
const freeSession = sessions.find((s) => !s.connectionId);
if (freeSession) {
const browser = await puppeteer.connect(env.MYBROWSER, freeSession.sessionId);
}
Playwright provides advanced testing features, assertions, and debugging.
Setup:
npm create cloudflare@latest -- browser-worker
cd browser-worker
npm install
wrangler dev # Local testing
wrangler deploy # Production
Advanced Playwright Worker:
import { Hono } from 'hono';
const app = new Hono<{ Bindings: Env }>();
app.get('/screenshot/:url', async (c) => {
const browser = await c.env.MYBROWSER.launch();
const page = await browser.newPage();
await page.goto(c.req.param('url'));
await page.waitForLoadState('networkidle');
const screenshot = await page.screenshot({ fullPage: true });
await browser.close();
return c.body(screenshot, 200, {
'Content-Type': 'image/png',
});
});
export default app;
Playwright-Specific Features:
expect(page).toHaveTitle())Storage State Caching:
// Save authentication state
const state = await page.context().storageState();
await env.KV.put('auth-state', JSON.stringify(state));
// Restore authentication state
const savedState = await env.KV.get('auth-state', 'json');
const context = await browser.newContext({ storageState: savedState });
Deploy Model Context Protocol server for LLM agent browser control.
Features:
Use Case: Enable AI agents to interact with web pages using structured accessibility data instead of screenshots.
Natural language browser automation powered by AI.
Example:
import { Stagehand } from '@stagehand-ai/stagehand';
const stagehand = new Stagehand(env.MYBROWSER);
await stagehand.init();
// Natural language instructions
await stagehand.act('click the login button');
await stagehand.act('fill in email with user@example.com');
const data = await stagehand.extract('get all product prices');
await stagehand.close();
Basic Setup:
name = "my-browser-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
browser = { binding = "MYBROWSER" }
Advanced Setup with Durable Objects and R2:
browser = { binding = "MYBROWSER" }
[[durable_objects.bindings]]
name = "BROWSER"
class_name = "Browser"
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-screenshots"
[[migrations]]
tag = "v1"
new_classes = ["Browser"]
Default Timeouts:
goToOptions.timeout: 30s (max 60s)waitForSelector: up to 60sactionTimeout: up to 5 minutesCustom Timeout Examples:
// Puppeteer
await page.goto(url, {
timeout: 60000, // 60 seconds
waitUntil: 'networkidle2',
});
await page.waitForSelector('.content', { timeout: 45000 });
// Playwright
await page.goto(url, {
timeout: 60000,
waitUntil: 'networkidle',
});
await page.locator('.element').click({ timeout: 10000 });
// Set viewport size
await page.setViewport({ width: 1920, height: 1080 });
// Screenshot options
const screenshot = await page.screenshot({
type: 'png', // "png" | "jpeg" | "webp"
quality: 90, // JPEG/WebP only, 0-100
fullPage: true, // Capture full scrollable page
clip: {
// Crop to specific area
x: 0,
y: 0,
width: 800,
height: 600,
},
});
const pdf = await page.pdf({
format: 'A4',
printBackground: true,
margin: {
top: '1cm',
right: '1cm',
bottom: '1cm',
left: '1cm',
},
displayHeaderFooter: true,
headerTemplate: '<div>Header</div>',
footerTemplate: '<div>Footer</div>',
});
Cost Optimization Tips:
disconnect() instead of close() for session reuseexport default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const targetUrl = url.searchParams.get('url');
// Check cache
const cached = await env.KV.get(targetUrl, 'arrayBuffer');
if (cached) {
return new Response(cached, {
headers: { 'Content-Type': 'image/png' },
});
}
// Generate screenshot
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto(targetUrl);
const screenshot = await page.screenshot();
await browser.close();
// Cache for 24 hours
await env.KV.put(targetUrl, screenshot, {
expirationTtl: 86400,
});
return new Response(screenshot, {
headers: { 'Content-Type': 'image/png' },
});
},
};
async function generateCertificate(name: string, env: Env) {
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
const html = `
<!DOCTYPE html>
<html>
<head>
<style>
body { font-family: Arial; text-align: center; padding: 50px; }
h1 { color: #2c3e50; font-size: 48px; }
</style>
</head>
<body>
<h1>Certificate of Achievement</h1>
<p>Awarded to: <strong>${name}</strong></p>
</body>
</html>
`;
await page.setContent(html);
const pdf = await page.pdf({
format: 'A4',
printBackground: true,
});
await browser.close();
return pdf;
}
import { Ai } from '@cloudflare/ai';
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Render page with Browser Rendering
const browser = await puppeteer.launch(env.MYBROWSER);
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com');
const content = await page.content();
await browser.close();
// Extract data with Workers AI
const ai = new Ai(env.AI);
const response = await ai.run('@hf/thebloke/deepseek-coder-6.7b-instruct-awq', {
messages: [
{
role: 'system',
content: 'Extract top 5 article titles and URLs as JSON array',
},
{
role: 'user',
content: content,
},
],
});
return Response.json(response);
},
};
export default {
async queue(batch: MessageBatch<any>, env: Env): Promise<void> {
const browser = await puppeteer.launch(env.MYBROWSER);
for (const message of batch.messages) {
const page = await browser.newPage();
await page.goto(message.body.url);
// Extract links
const links = await page.evaluate(() => {
return Array.from(document.querySelectorAll('a')).map((a) => a.href);
});
// Queue new links
for (const link of links) {
await env.QUEUE.send({ url: link });
}
await page.close();
}
await browser.close();
},
};
export class Browser {
state: DurableObjectState;
browser: any;
lastUsed: number;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
this.lastUsed = Date.now();
}
async fetch(request: Request, env: Env) {
// Initialize browser on first request
if (!this.browser) {
this.browser = await puppeteer.launch(env.MYBROWSER);
}
// Set keep-alive alarm
this.lastUsed = Date.now();
await this.state.storage.setAlarm(Date.now() + 10000);
const page = await this.browser.newPage();
await page.goto(new URL(request.url).searchParams.get('url'));
const screenshot = await page.screenshot();
await page.close();
return new Response(screenshot, {
headers: { 'Content-Type': 'image/png' },
});
}
async alarm() {
// Close browser if idle for 60 seconds
if (Date.now() - this.lastUsed > 60000) {
await this.browser?.close();
this.browser = null;
} else {
await this.state.storage.setAlarm(Date.now() + 10000);
}
}
}
disconnect() instead of close() to keep sessions alive for reusewaitUntil strategy (load, networkidle0, networkidle2)Timeout Errors:
page.goto(url, { timeout: 60000 }){ waitUntil: "domcontentloaded" }Rate Limit (429) Errors:
Session Connection Failures:
Memory Issues:
await page.close()await browser.disconnect()Font Rendering Issues:
url (required) - Target webpage URLwaitDelay - Wait time in milliseconds (0-30000)goto.timeout - Navigation timeout (0-60000ms)goto.waitUntil - Wait strategy (load, domcontentloaded, networkidle)puppeteer.launch(binding) - Start browserpuppeteer.connect(binding, sessionId) - Reconnect to sessionpuppeteer.sessions(binding) - List active sessionsbrowser.newPage() - Create new pagebrowser.disconnect() - Disconnect keeping session alivebrowser.close() - Close and terminate sessionpage.goto(url, options) - Navigatepage.screenshot(options) - Capture screenshotpage.pdf(options) - Generate PDFpage.content() - Get HTMLpage.evaluate(fn) - Execute JavaScriptenv.MYBROWSER.launch() - Start browserbrowser.newPage() - Create new pagebrowser.newContext(options) - Create context with statepage.goto(url, options) - Navigatepage.screenshot(options) - Capture screenshotpage.pdf(options) - Generate PDFpage.locator(selector) - Find elementpage.waitForLoadState(state) - Wait for loadcontext.storageState() - Get authentication statePre-installed fonts include:
Custom Font Injection:
<link href="https://fonts.googleapis.com/css2?family=Poppins" rel="stylesheet" />
Setup:
npm install -g wranglerwrangler loginnpm create cloudflare@latestConfiguration:
wrangler.tomlTesting:
wrangler devDeployment:
wrangler deployWhen implementing Cloudflare Browser Rendering:
Choose Integration Method:
Set Up Configuration:
wrangler.toml with appropriate bindings@cloudflare/puppeteer or @cloudflare/workers-playwright)Implement Core Logic:
Optimize for Cost:
disconnect()Deploy and Monitor:
wrangler devwrangler deploy
