Pular para o conteúdo

Get started

Atualizado em Ver como Markdown

Cloudflare Browser Run (formerly Browser Rendering) allows you to programmatically control a headless browser, enabling you to do things like take screenshots, generate PDFs, and perform automated browser tasks. This guide will help you choose the right integration method and get you started with your first project.

Browser Run offers two categories of integration methods:

  • Quick Actions: Simple, stateless browser tasks like screenshots, PDFs, and scraping. No code deployment needed.
  • Browser Sessions: Direct browser control via Puppeteer, Playwright, CDP, or Stagehand. Deploy within Cloudflare Workers or connect from any environment via CDP.
Use case Recommended Why
Simple screenshot, PDF, or scrape Quick Actions No code deployment; single HTTP request
Browser automation Playwright, Puppeteer, or CDP Full browser control with scripting
Porting existing scripts Puppeteer, Playwright, or CDP Minimal code changes from standard libraries
AI-powered data extraction JSON endpoint Structured data via natural language prompts
Site-wide crawling Crawl endpoint Multi-page content extraction with async results
AI agent browsing Playwright MCP or CDP with MCP clients LLMs control browsers via MCP
Resilient scraping Stagehand AI finds elements by intent, not selectors
Direct browser control from any environment CDP WebSocket access from local machines, CI/CD, or external servers

Quick Actions

Quick Actions can be used via the REST API or directly from a Cloudflare Worker using a browser binding.

Prerequisites

Example: Take a screenshot

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }' \
  --output "screenshot.png"

Prerequisites

Example: Take a screenshot from a Worker

1. Create a Worker project

Create a new Worker project named browser-quick-action by running:


								
									
									npm
									 create cloudflare@latest -- browser-quick-action

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose TypeScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

2. Configure the browser binding

Update your Wrangler configuration file with a browser binding:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "browser-quick-action",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-07-20",
  "browser": {
    "binding": "BROWSER"
  }
}
name = "browser-quick-action"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-07-20"

[browser]
binding = "BROWSER"

3. Write the Worker code

Replace the contents of src/index.ts with the following:

export default {
	async fetch(request, env) {
		return await env.BROWSER.quickAction("screenshot", {
			url: "https://example.com",
		});
	},
};
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("screenshot", {
			url: "https://example.com",
		});
	},
} satisfies ExportedHandler<Env>;

This Worker uses the browser binding to take a screenshot of example.com and returns the image directly in the response.

4. Test

Run npx wrangler dev --remote to test your Worker locally.

Visit your local URL to see the screenshot.

5. Deploy

Run npx wrangler deploy to deploy your Worker to the Cloudflare global network.

Other Quick Actions endpoints include:

Check out the full list of Quick Actions endpoints.

Browser Sessions

Prerequisites

  1. Sign up for a Cloudflare account ↗.
  2. Install Node.js ↗.

Node.js version manager

Use a Node version manager like Volta ↗ or nvm ↗ to avoid permission issues and change Node.js versions. Wrangler, discussed later in this guide, requires a Node version of 16.17.0 or later.

Example: Navigate to a URL, take a screenshot, and store in KV

1. Create a Worker project

Cloudflare Workers provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure. Your Worker application is a container to interact with a headless browser to do actions, such as taking screenshots.

Create a new Worker project named browser-worker by running:


								
									
									npm
									 create cloudflare@latest -- browser-worker

For setup, select the following options:

  • For What would you like to start with?, choose Hello World example.
  • For Which template would you like to use?, choose Worker only.
  • For Which language do you want to use?, choose JavaScript / TypeScript.
  • For Do you want to use git for version control?, choose Yes.
  • For Do you want to deploy your application?, choose No (we will be making some changes before deploying).

2. Install Puppeteer

In your browser-worker directory, install Cloudflare’s fork of Puppeteer:


								
									
									npm
									 i -D @cloudflare/puppeteer

3. Create a KV namespace

Browser Run can be used with other developer products. You might need a relational database, an R2 bucket to archive your crawled pages and assets, a Durable Object to keep your browser instance alive and share it with multiple requests, or Queues to handle your jobs asynchronously.

For the purpose of this example, we will use a KV store to cache your screenshots.

Create two namespaces, one for production and one for development.

npx wrangler kv namespace create BROWSER_KV_DEMO
npx wrangler kv namespace create BROWSER_KV_DEMO --preview

Take note of the IDs for the next step.

4. Configure the Wrangler configuration file

Configure your browser-worker project's Wrangler configuration file by adding a browser binding and a Node.js compatibility flag. Bindings allow your Workers to interact with resources on the Cloudflare developer platform. Your browser binding name is set by you, this guide uses the name MYBROWSER. Browser bindings allow for communication between a Worker and a headless browser which allows you to do actions such as taking a screenshot, generating a PDF, and more.

Update your Wrangler configuration file with the Browser Run API binding and the KV namespaces you created:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "browser-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-07-20",
	"compatibility_flags": ["nodejs_compat"],
	"browser": {
		"binding": "MYBROWSER"
	},
	"kv_namespaces": [
		{
			"binding": "BROWSER_KV_DEMO",
			"id": "22cf855786094a88a6906f8edac425cd",
			"preview_id": "e1f8b68b68d24381b57071445f96e623"
		}
	]
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "browser-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-07-20"
compatibility_flags = [ "nodejs_compat" ]

[browser]
binding = "MYBROWSER"

[[kv_namespaces]]
binding = "BROWSER_KV_DEMO"
id = "22cf855786094a88a6906f8edac425cd"
preview_id = "e1f8b68b68d24381b57071445f96e623"

5. Code

Update src/index.js with your Worker code:

import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = await page.screenshot();
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
};

Update src/index.ts with your Worker code:

import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
	BROWSER_KV_DEMO: KVNamespace;
}

export default {
	async fetch(request, env): Promise<Response> {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img: Buffer;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = (await page.screenshot()) as Buffer;
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
} satisfies ExportedHandler<Env>;

This Worker instantiates a browser using Puppeteer, opens a new page, navigates to the location of the 'url' parameter, takes a screenshot of the page, stores the screenshot in KV, closes the browser, and responds with the JPEG image of the screenshot.

If your Worker is running in production, it will store the screenshot to the production KV namespace. If you are running wrangler dev, it will store the screenshot to the dev KV namespace.

If the same url is requested again, it will use the cached version in KV instead, unless it expired.

6. Test

Run npx wrangler dev to test your Worker locally.

To test taking your first screenshot, go to the following URL:

<LOCAL_HOST_URL>/?url=https://example.com

7. Deploy

Run npx wrangler deploy to deploy your Worker to the Cloudflare global network.

To take your first screenshot, go to the following URL:

<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?url=https://example.com

Next steps

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the Cloudflare Developers community on Discord ↗.