diff --git a/src/content/docs/browser-rendering/get-started.mdx b/src/content/docs/browser-rendering/get-started.mdx index 9efeb8ac79e2a36..487c063e35f3312 100644 --- a/src/content/docs/browser-rendering/get-started.mdx +++ b/src/content/docs/browser-rendering/get-started.mdx @@ -4,8 +4,54 @@ title: Get started sidebar: order: 2 --- +import { Render } from "~/components"; -Browser rendering can be used in two ways: +Cloudflare 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. -- [Workers Bindings](/browser-rendering/workers-bindings/) for complex scripts. -- [REST API](/browser-rendering/rest-api/) for simple actions. +There are two ways to use Browser Rendering: +- [REST API](/browser-rendering/rest-api/) for simple, one-off actions, like taking a screenshot, fetching HTML, or generating a PDF. +- [Workers Bindings](/browser-rendering/workers-bindings/) for more complex, multi-step browser automation using [Puppeteer](/browser-rendering/platform/puppeteer/) and [Playwright](/browser-rendering/platform/playwright/). + +This guide will help you choose the right path for your needs and get you started with your first Browser Rendering project. + +## REST API + +The REST API is best for situations where you have an existing application and want to perform simple, stateless browser actions. + +### Prerequisites +- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages). +- Create a [Cloudflare API Token](/fundamentals/api/get-started/create-token/) with `Browser Rendering - Edit` permissions. + +### Example: Take a screenshot of the Cloudflare homepage + + + +The REST API can also be used to: + +- [Fetch HTML](/browser-rendering/rest-api/content-endpoint/) +- [Generate a PDF](/browser-rendering/rest-api/pdf-endpoint/) +- [and more...](/browser-rendering/rest-api/) + +## Workers Bindings + +Workers Bindings are best for situations where you need to build more complex, multi-step browser automation workflows. You can use familiar tools like [Puppeteer](/browser-rendering/platform/puppeteer/) and [Playwright](/browser-rendering/platform/playwright/). + +### Prerequisites + + +### Example: Navigate to a URL, take a screenshot, and store in KV + + + +## 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](https://discord.cloudflare.com/). + +- Check out all the [REST API endpoints](/browser-rendering/rest-api/) +- Try out the [Playwright MCP](/browser-rendering/platform/playwright-mcp/) +- Learn more about Browser Rendering [limits](/browser-rendering/platform/limits/) and [pricing](/browser-rendering/platform/pricing/). diff --git a/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx b/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx index 7ff9febb07e4378..ee2d3d72e76ce6e 100644 --- a/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx +++ b/src/content/docs/browser-rendering/workers-bindings/screenshots.mdx @@ -17,174 +17,11 @@ By following this guide, you will create a Worker that uses the Browser Renderin -## 1. Create a Worker project - -[Cloudflare Workers](/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: - - - -## 2. Install Puppeteer - -In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/): - - - -## 3. Create a KV namespace - -Browser Rendering can be used with other developer products. You might need a [relational database](/d1/), an [R2 bucket](/r2/) to archive your crawled pages and assets, a [Durable Object](/durable-objects/) to keep your browser instance alive and share it with multiple requests, or [Queues](/queues/) to handle your jobs asynchronous. - -For the purpose of this guide, you are going to use a [KV store](/kv/concepts/kv-namespaces/) to cache your screenshots. - -Create two namespaces, one for production, and one for development. - -```sh -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](/workers/wrangler/configuration/) by adding a browser [binding](/workers/runtime-apis/bindings/) and a [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-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](/workers/wrangler/configuration/) with the Browser Rendering API binding and the KV namespaces you created: - - - -```toml title="wrangler.toml" -name = "browser-worker" -main = "src/index.js" -compatibility_date = "2023-03-14" -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: - -```js -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: - -```ts -import puppeteer from "@cloudflare/puppeteer"; - -interface Env { - MYBROWSER: Fetcher; - BROWSER_KV_DEMO: KVNamespace; -} - -export default { - async fetch(request, env): Promise { - 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; -``` - - - -This Worker instantiates a browser using Puppeteer, opens a new page, navigates to what you put in 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. You can also use [remote bindings](/workers/development-testing/#remote-bindings) to test against a remote browser. - -To test taking your first screenshot, go to the following 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: - -`..workers.dev/?url=https://example.com` - ## Related resources - Other [Puppeteer examples](https://github.com/cloudflare/puppeteer/tree/main/examples) diff --git a/src/content/partials/browser-rendering/example-workers-binding-screenshots-from-web.mdx b/src/content/partials/browser-rendering/example-workers-binding-screenshots-from-web.mdx new file mode 100644 index 000000000000000..f1e16db47da6655 --- /dev/null +++ b/src/content/partials/browser-rendering/example-workers-binding-screenshots-from-web.mdx @@ -0,0 +1,169 @@ +import { Render, PackageManagers, WranglerConfig, Tabs, TabItem } from "~/components"; + +#### 1. Create a Worker project + +[Cloudflare Workers](/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: + + + + + +#### 2. Install Puppeteer + +In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/): + + + +#### 3. Create a KV namespace + +Browser Rendering can be used with other developer products. You might need a [relational database](/d1/), an [R2 bucket](/r2/) to archive your crawled pages and assets, a [Durable Object](/durable-objects/) to keep your browser instance alive and share it with multiple requests, or [Queues](/queues/) to handle your jobs asynchronously. + +For the purpose of this example, we will use a [KV store](/kv/concepts/kv-namespaces/) to cache your screenshots. + +Create two namespaces, one for production and one for development. + +```sh +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](/workers/wrangler/configuration/) by adding a browser [binding](/workers/runtime-apis/bindings/) and a [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-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](/workers/wrangler/configuration/) with the Browser Rendering API binding and the KV namespaces you created: + + + +```toml title="wrangler.toml" +name = "browser-worker" +main = "src/index.js" +compatibility_date = "2023-03-14" +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: + +```js +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: + +```ts +import puppeteer from "@cloudflare/puppeteer"; + +interface Env { + MYBROWSER: Fetcher; + BROWSER_KV_DEMO: KVNamespace; +} + +export default { + async fetch(request, env): Promise { + 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; +``` + + + +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 or run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network. + +To test taking your first screenshot, go to the following 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: + +`..workers.dev/?url=https://example.com`