How does a Cloudflare Worker get a headless browser from Browser Run, and what must its Wrangler file declare?
answer
- a binding, not an API token
- browser block plus nodejs_compat
- Cloudflare's forks of two libraries
- close it in finally
basics
~10 sThe Wrangler file declares a browser binding and the nodejs_compat flag; the Worker passes that binding to launch() from @cloudflare/puppeteer or @cloudflare/playwright, drives the returned browser, and calls browser.close() when it is done.
solid answer
~30 sThe Wrangler file gets a `browser` block such as `"browser": { "binding": "MYBROWSER" }` and `"compatibility_flags": ["nodejs_compat"]`. The binding is an authenticated endpoint to a Chromium instance on Cloudflare's network, so the Worker needs no API token. In code, `puppeteer.launch(env.MYBROWSER)` from `@cloudflare/puppeteer`, or `launch(env.MYBROWSER)` from `@cloudflare/playwright`, returns a browser, and the rest is the library's normal page API. Call `browser.close()` in a `finally` block: a browser that is never closed stays open until 60 seconds pass with no commands, and that time is billed. The `browser` key is not inherited by Wrangler environments, so each environment repeats it.
code
json · 9 lines{
"name": "preview-worker",
"main": "src/index.ts",
"compatibility_date": "2026-10-10",
"compatibility_flags": ["nodejs_compat"],
"browser": {
"binding": "MYBROWSER"
}
}go deeper
Recall the three pieces: a browser binding in the Wrangler file, the nodejs_compat flag, and launch() from Cloudflare's Puppeteer or Playwright fork with the binding passed in.
Explain why no token is needed, why the forks exist, and why browser.close() belongs in a finally block given the 60-second idle timeout.
Show you know what a first deployment trips over: the non-inheritable browser key, the Free plan's ten browser minutes a day, and launches that fail with 429.
Frame the binding as the boundary: the Worker holds no credential, and the team decides which Workers get a browser binding at all.
## What the browser binding is **Browser Run** (formerly Browser Rendering) runs headless Chromium on Cloudflare's network. A Worker reaches it through a **binding**: a named entry on `env` that the runtime wires to the service for the Worker's own account. The binding is an authenticated endpoint, so the Worker carries no Cloudflare API token. For the scenario of this lesson, a Worker that renders invoices to PDF and screenshots customers' public pages for link previews, the binding is the first thing the project needs. ## Declaring it in the Wrangler file Three settings matter: - a `browser` block with a `binding` name of your choice (`MYBROWSER`, `BROWSER`); - the `nodejs_compat` compatibility flag, because Cloudflare's library forks use Node.js APIs; - a recent `compatibility_date`: the current `@cloudflare/playwright` needs 2025-09-15 or later, and the binding's `quickAction()` method needs 2026-03-24 or later. The `browser` key is **non-inheritable**: a named Wrangler environment such as `staging` does not pick it up from the top level and must declare its own. ## Launching a browser Browser Run ships two forks that accept the binding instead of a local DevTools port: | Library | Install | Launch call | |---|---|---| | Puppeteer | `@cloudflare/puppeteer` | `puppeteer.launch(env.MYBROWSER)` | | Playwright | `@cloudflare/playwright` | `launch(env.MYBROWSER)` | After launch, a page is opened and driven with the library's ordinary API: `browser.newPage()`, `page.goto()`, `page.screenshot()`, `page.pdf()`. The library APIs themselves are covered with Puppeteer and Playwright; what Browser Run adds is the launch, the session methods and the limits. A few fork-specific differences are worth knowing: - the Puppeteer fork does not support XPath selectors in the Workers runtime; use CSS selectors, or run XPath inside `page.evaluate()`; - the Playwright fork does not yet support everything upstream does, for example browsers other than Chromium, video recording, and Playwright Test apart from its assertions; - setting a custom user agent does not hide the browser from bot detection: Browser Run requests are always identified as a bot. ## Closing the browser Every launch starts a **browser session**. It ends in one of these ways: 1. the code calls `browser.close()` (a normal closure); 2. no command arrives for the idle timeout, 60 seconds by default and up to 10 minutes with the `keep_alive` option; 3. Browser Run ends it, for example when a new release rolls out, Chromium crashes or the client's connection drops. Until it ends, the session uses browser time. A Worker that throws before `browser.close()` leaves the browser idling, so the call belongs in a `finally` block. Leaving a browser open on purpose, so a later request can attach to it, is session reuse, which needs its own design. ## What a first Worker runs into | Limit | Workers Free | Workers Paid (defaults as of 2026-10-10) | |---|---|---| | Browser time | 10 minutes per day | 10 hours a month included, then billed per hour | | Concurrent browsers | 3 per account | 200 per account by default | | New browser instances | 1 every 20 seconds | 3 per second | On the Free plan a link-preview Worker can exhaust ten browser minutes quickly, after which launches fail with a `429` until the next UTC day. ## Puppeteer, Playwright or neither Both forks reach the same browser through the same binding, so the choice is mostly about the team's existing scripts and taste. Two version notes matter: sharing one session among several concurrent clients needs `@cloudflare/puppeteer` 1.1.0 or `@cloudflare/playwright` 1.3.0 or later, and the Playwright fork's import is a named `launch` rather than a default export. For a job that one request fully describes, such as "screenshot this URL" or "render this HTML to PDF", a third route skips the library altogether: Browser Run's **Quick Actions**, called over REST or through the same binding's `quickAction()` method, manage the browser for you. ## A checklist before the first deploy 1. The `browser` binding is declared at the top level and in every named environment. 2. `nodejs_compat` is set and the compatibility date is recent enough for the fork in use. 3. Every `launch()` has a matching `browser.close()` in a `finally` block. 4. The page timeouts leave room inside the Worker's own limits, since a Worker that dies mid-session drops its connection to the browser.
- Why does the Worker not need a Cloudflare API token to use Browser Run?The `browser` binding is an authenticated endpoint the runtime wires to the Worker's own account, so the Worker never holds a credential. An API token with the `Browser Run - Edit` permission is only needed when calling Browser Run's REST endpoints from outside a Worker, for example from a CI job or another server.
- A staging deployment of the Worker fails with env.MYBROWSER undefined although production works; why?The `browser` key is non-inheritable in Wrangler: a named environment does not copy it from the top level. The `staging` environment block needs its own `browser` entry with the binding name, just as it repeats KV namespaces and other bindings.
- Browser Run needs an API token stored as a Worker secret
- Upstream Puppeteer connects to Browser Run without the Cloudflare fork
- The browser closes by itself when the fetch handler returns
- A custom user agent stops Browser Run being seen as a bot
- A browser block at the top level covers every Wrangler environment
Assumes Browser Run as of 2026-10-10, renamed from Browser Rendering on 2026-04-15; the Workers Paid defaults of 200 concurrent browsers and 3 new browsers per second date from 2026-08-20.