Skip to content

browser-rendering-with-DO.mdx

Latest commit

 

History

History
256 lines (199 loc) · 8.14 KB

browser-rendering-with-DO.mdx

File metadata and controls

256 lines (199 loc) · 8.14 KB
pcx_content_type tutorial
title Deploy a Browser Rendering Worker with Durable Objects
products
workers
durable-objects
r2
difficulty Beginner
reviewed 2023-09-28
tags
JavaScript
sidebar
order
2
description Use the Browser Rendering API along with Durable Objects to take screenshots from web pages and store them in R2.

import { Render, PackageManagers, WranglerConfig, TypeScriptExample } from "~/components";

By following this guide, you will create a Worker that uses the Browser Rendering API along with Durable Objects to take screenshots from web pages and store them in R2.

Using Durable Objects to persist browser sessions improves performance by eliminating the time that it takes to spin up a new browser session. Since Durable Objects re-uses sessions, it reduces the number of concurrent sessions needed.

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:

<PackageManagers type="create" pkg="cloudflare@latest" args={"browser-worker"} />

2. Install Puppeteer

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

3. Create a R2 bucket

Create two R2 buckets, one for production, and one for development.

Note that bucket names must be lowercase and can only contain dashes.

wrangler r2 bucket create screenshots
wrangler r2 bucket create screenshots-test

To check that your buckets were created, run:

wrangler r2 bucket list

After running the list command, you will see all bucket names, including the ones you have just created.

4. Configure your Wrangler configuration file

Configure your browser-worker project's Wrangler configuration file by adding a browser binding and a Node.js compatibility flag. 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 Rendering API binding, the R2 bucket you created and a Durable Object:

:::note Your Worker configuration must include the nodejs_compat compatibility flag and a compatibility_date of 2025-09-15 or later. :::

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "rendering-api-demo",
	"main": "src/index.js",
	"compatibility_date": "$today",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"account_id": "<ACCOUNT_ID>",
	// Browser Rendering API binding
	"browser": {
		"binding": "MYBROWSER"
	},
	// Bind an R2 Bucket
	"r2_buckets": [
		{
			"binding": "BUCKET",
			"bucket_name": "screenshots",
			"preview_bucket_name": "screenshots-test"
		}
	],
	// Binding to a Durable Object
	"durable_objects": {
		"bindings": [
			{
				"name": "BROWSER",
				"class_name": "Browser"
			}
		]
	},
	"migrations": [
		{
			"tag": "v1", // Should be unique for each entry
			"new_sqlite_classes": [ // Array of new classes
				"Browser"
			]
		}
	]
}

5. Code

The code below uses Durable Object to instantiate a browser using Puppeteer. It then opens a series of web pages with different resolutions, takes a screenshot of each, and uploads it to R2.

The Durable Object keeps a browser session open for 60 seconds after last use. If a browser session is open, any requests will re-use the existing session rather than creating a new one. Update your Worker code by copy and pasting the following:

```ts import { DurableObject } from "cloudflare:workers"; import * as puppeteer from "@cloudflare/puppeteer";

interface Env { MYBROWSER: Fetcher; BUCKET: R2Bucket; BROWSER: DurableObjectNamespace; }

export default { async fetch(request, env): Promise { const obj = env.BROWSER.getByName("browser");

// Send a request to the Durable Object, then await its response
const resp = await obj.fetch(request);

return resp;

}, } satisfies ExportedHandler;

const KEEP_BROWSER_ALIVE_IN_SECONDS = 60;

export class Browser extends DurableObject { private browser?: puppeteer.Browser; private keptAliveInSeconds: number = 0; private storage: DurableObjectStorage;

constructor(state: DurableObjectState, env: Env) { super(state, env); this.storage = state.storage; }

async fetch(request: Request): Promise { // Screen resolutions to test out const width: number[] = [1920, 1366, 1536, 360, 414]; const height: number[] = [1080, 768, 864, 640, 896];

// Use the current date and time to create a folder structure for R2
const nowDate = new Date();
const coeff = 1000 * 60 * 5;
const roundedDate = new Date(
  Math.round(nowDate.getTime() / coeff) * coeff,
).toString();
const folder = roundedDate.split(" GMT")[0];

// If there is a browser session open, re-use it
if (!this.browser || !this.browser.isConnected()) {
  console.log(`Browser DO: Starting new instance`);
  try {
    this.browser = await puppeteer.launch(this.env.MYBROWSER);
  } catch (e) {
    console.log(
      `Browser DO: Could not start browser instance. Error: ${e}`,
    );
  }
}

// Reset keptAlive after each call to the DO
this.keptAliveInSeconds = 0;

// Check if browser exists before opening page
if (!this.browser) return new Response("Browser launch failed", { status: 500 });

const page = await this.browser.newPage();

// Take screenshots of each screen size
for (let i = 0; i < width.length; i++) {
  await page.setViewport({ width: width[i], height: height[i] });
  await page.goto("https://workers.cloudflare.com/");
  const fileName = `screenshot_${width[i]}x${height[i]}`;
  const sc = await page.screenshot();

  await this.env.BUCKET.put(`${folder}/${fileName}.jpg`, sc);
}

// Close tab when there is no more work to be done on the page
await page.close();

// Reset keptAlive after performing tasks to the DO
this.keptAliveInSeconds = 0;

// Set the first alarm to keep DO alive
const currentAlarm = await this.storage.getAlarm();
if (currentAlarm == null) {
  console.log(`Browser DO: setting alarm`);
  const TEN_SECONDS = 10 * 1000;
  await this.storage.setAlarm(Date.now() + TEN_SECONDS);
}

return new Response("success");

}

async alarm(): Promise { this.keptAliveInSeconds += 10;

// Extend browser DO life
if (this.keptAliveInSeconds < KEEP_BROWSER_ALIVE_IN_SECONDS) {
  console.log(
    `Browser DO: has been kept alive for ${this.keptAliveInSeconds} seconds. Extending lifespan.`,
  );
  await this.storage.setAlarm(Date.now() + 10 * 1000);
  // You can ensure the ws connection is kept alive by requesting something
  // or just let it close automatically when there is no work to be done
  // for example, `await this.browser.version()`
} else {
  console.log(
    `Browser DO: exceeded life of ${KEEP_BROWSER_ALIVE_IN_SECONDS}s.`,
  );
  if (this.browser) {
    console.log(`Closing browser.`);
    await this.browser.close();
  }
}

} }

</TypeScriptExample>

## 6. Test

Run `npx wrangler dev` to test your Worker locally.

<Render file="remote-binding-note" product="workers" />

## 7. Deploy

Run [`npx wrangler deploy`](/workers/wrangler/commands/general/#deploy) to deploy your Worker to the Cloudflare global network.

## Related resources

- Other [Puppeteer examples](https://github.com/cloudflare/puppeteer/tree/main/examples)
- Get started with [Durable Objects](/durable-objects/get-started/)
- [Using R2 from Workers](/r2/api/workers/workers-api-usage/)