From 8c80146880a2dad3cd97b01befec0f94900edffe Mon Sep 17 00:00:00 2001 From: rcorreia Date: Thu, 29 Oct 2026 19:12:14 +0000 Subject: [PATCH] [Browser Run] Document Quick Actions in local development `.quickAction()` now runs against a local Chrome under `wrangler dev` (cloudflare/workers-sdk#16589). Remove the remote-mode requirement and document the two local limits: the `json` action returns placeholder data, and the Kitesurf browser is not available. --- src/content/docs/browser-run/faq.mdx | 4 ++- .../browser-run/how-to/pre-render-pages.mdx | 8 +++--- src/content/docs/browser-run/kitesurf.mdx | 2 ++ .../docs/browser-run/quick-actions/index.mdx | 26 ++++++++++++++----- .../quick-actions/json-endpoint.mdx | 1 + .../docs/browser-run/reference/wrangler.mdx | 10 +++---- .../example-quick-action-binding.mdx | 2 +- 7 files changed, 36 insertions(+), 17 deletions(-) diff --git a/src/content/docs/browser-run/faq.mdx b/src/content/docs/browser-run/faq.mdx index ed6c7544b30..08ed77862d8 100644 --- a/src/content/docs/browser-run/faq.mdx +++ b/src/content/docs/browser-run/faq.mdx @@ -93,9 +93,11 @@ Browser sessions open on Cloudflare's global network, close to the incoming requ ### Does local development support all Browser Run features? -Not yet. Local development currently has the following limitation(s): +Not yet. Local development currently has the following limitations: - Requests larger than 1 MB are not supported. +- The `json` [Quick Action](/browser-run/quick-actions/) returns placeholder data, because Workers AI is not available locally. Refer to [Test Quick Actions locally](/browser-run/quick-actions/#test-quick-actions-locally). +- The [Kitesurf](/browser-run/kitesurf/) browser is not available. You can also run Chrome in visible (headful) mode during local development to visually debug your automation scripts (experimental). Set the `X_BROWSER_HEADFUL` environment variable before starting your dev server: diff --git a/src/content/docs/browser-run/how-to/pre-render-pages.mdx b/src/content/docs/browser-run/how-to/pre-render-pages.mdx index 34a2bcd89a6..0466a339c11 100644 --- a/src/content/docs/browser-run/how-to/pre-render-pages.mdx +++ b/src/content/docs/browser-run/how-to/pre-render-pages.mdx @@ -28,7 +28,7 @@ In this tutorial, you will: - Add a Browser Run binding to a Worker - Create a minimal pre-rendering endpoint - Restrict which hostnames the Worker can render -- Test the endpoint locally with remote mode +- Test the endpoint locally ## Prerequisites @@ -165,11 +165,11 @@ The `waitUntil: "networkidle2"` option waits until the page has no more than two -1. Start your Worker in remote mode: +1. Start your Worker locally: - + - The `.quickAction()` method is not yet supported in local development mode. Use `wrangler dev --remote` when testing Browser Run Quick Actions locally. + Wrangler runs the `.quickAction()` call against a Chrome instance on your machine. 2. In another terminal, request a rendered page: diff --git a/src/content/docs/browser-run/kitesurf.mdx b/src/content/docs/browser-run/kitesurf.mdx index 677023aca03..bad74cf63de 100644 --- a/src/content/docs/browser-run/kitesurf.mdx +++ b/src/content/docs/browser-run/kitesurf.mdx @@ -84,6 +84,8 @@ export default { The binding validates the value, so any engine name other than `kitesurf` fails with `Invalid input: expected "kitesurf"`. Leave out `browser` to use the default Chromium browser. +Under `wrangler dev`, a `.quickAction()` call with `browser: "kitesurf"` throws an error, because Kitesurf is not available locally. To use Kitesurf during local development, set `"remote": true` in your browser binding configuration. + ### Use Kitesurf with the CDP endpoint The [Browser Run CDP endpoint](/browser-run/cdp/) supports Kitesurf as an option, so your existing [Puppeteer](/browser-run/puppeteer/), [Playwright](/browser-run/playwright/), or [chrome-remote-interface](https://www.npmjs.com/package/chrome-remote-interface) setup already works. To opt in, add `browser=kitesurf` to the endpoint URL: diff --git a/src/content/docs/browser-run/quick-actions/index.mdx b/src/content/docs/browser-run/quick-actions/index.mdx index d27495b2a92..e0151c8ab1d 100644 --- a/src/content/docs/browser-run/quick-actions/index.mdx +++ b/src/content/docs/browser-run/quick-actions/index.mdx @@ -45,23 +45,37 @@ To use Quick Actions from a [Worker](/workers/), configure a [browser binding](/ :::caution -The `.quickAction()` method has two requirements: - -- **Compatibility date:** Your Worker must use a compatibility date of `2026-03-24` or later. -- **Remote mode for local development:** The `.quickAction()` method is not yet supported in local development mode. When developing locally with `wrangler dev`, you must use `npx wrangler dev --remote` or set `"remote": true` in your browser binding configuration. Without remote mode, you will receive the error: `The RPC receiver does not implement the method "quickAction"`. +The `.quickAction()` method requires a compatibility date of `2026-03-24` or later. ```jsonc { "compatibility_date": "2026-03-24", "browser": { - "binding": "BROWSER", - "remote": true + "binding": "BROWSER" } } ``` ::: +### Test Quick Actions locally + +Under `npx wrangler dev`, `.quickAction()` uses a Chrome instance on your machine. It returns the same responses and errors as Browser Run, with two exceptions: + +- The `json` action returns placeholder data, because [Workers AI](/workers-ai/) is not available locally. If a field in `response_format.json_schema` sets `const`, `enum`, or `default`, it gets that value, or the first `enum` entry. Other fields get an empty value, such as `""`, `0`, `false`, or `[]`. Wrangler also logs a warning. +- The [Kitesurf](/browser-run/kitesurf/) browser is not available. If you pass `browser: "kitesurf"`, `.quickAction()` throws an error. + +To get real `json` results or use Kitesurf during local development, set `"remote": true` in your browser binding configuration: + +```jsonc +{ + "browser": { + "binding": "BROWSER", + "remote": true + } +} +``` + :::note[Note] You can monitor Browser Run (formerly Browser Rendering) usage in two ways: diff --git a/src/content/docs/browser-run/quick-actions/json-endpoint.mdx b/src/content/docs/browser-run/quick-actions/json-endpoint.mdx index 2cb94f57d89..35792f8b1cf 100644 --- a/src/content/docs/browser-run/quick-actions/json-endpoint.mdx +++ b/src/content/docs/browser-run/quick-actions/json-endpoint.mdx @@ -427,6 +427,7 @@ If the `/json` endpoint returns null or empty results: - **Provide a clear prompt** — Be specific about what data to extract and where it appears on the page (for example, "Extract the product name, price, and description from the main product section"). - **Define a response schema** — Use `response_format` with a JSON schema to enforce the expected output structure. - **Use a custom model** — If the default [Workers AI](/workers-ai/) model does not produce the desired results, use the `custom_ai` parameter to specify a different model. Refer to [Using a custom model (BYO API Key)](/browser-run/quick-actions/json-endpoint/#using-a-custom-model-byo-api-key) for details. +- **Use remote mode in local development** — Under `wrangler dev`, the `json` action returns placeholder data shaped like `response_format.json_schema`, because Workers AI is not available locally. To extract real data, set `"remote": true` in your browser binding configuration. Refer to [Test Quick Actions locally](/browser-run/quick-actions/#test-quick-actions-locally). diff --git a/src/content/docs/browser-run/reference/wrangler.mdx b/src/content/docs/browser-run/reference/wrangler.mdx index 5360726e84e..4d1719a3986 100644 --- a/src/content/docs/browser-run/reference/wrangler.mdx +++ b/src/content/docs/browser-run/reference/wrangler.mdx @@ -65,9 +65,11 @@ The browser binding's `.quickAction()` method requires a compatibility date of ` ::: -:::caution[Quick Actions require remote mode for local development] +To test a Worker locally, run `npx wrangler dev`. Wrangler runs Puppeteer, Playwright, CDP, and `.quickAction()` calls against Chrome on your machine. -The `.quickAction()` method is not yet supported in local development mode. When using `wrangler dev`, you must run with `--remote` or set `"remote": true` in your browser binding configuration: +:::note[Some Quick Actions need remote mode] + +[Workers AI](/workers-ai/) is not available locally, so the `json` Quick Action returns placeholder data shaped like `response_format.json_schema`. The [Kitesurf](/browser-run/kitesurf/) browser is not available locally either. To get real `json` results or use Kitesurf, set `"remote": true` in your browser binding configuration: ```jsonc { @@ -78,12 +80,10 @@ The `.quickAction()` method is not yet supported in local development mode. When } ``` -Without remote mode, calls to `.quickAction()` will fail with: `The RPC receiver does not implement the method "quickAction"`. +For details, refer to [Test Quick Actions locally](/browser-run/quick-actions/#test-quick-actions-locally). ::: -For Puppeteer, Playwright, or CDP-based Workers, run `npx wrangler dev` to test locally. For Quick Actions via `.quickAction()`, use `npx wrangler dev --remote` as noted above. - ### Headful mode (experimental) By default, local development runs Chrome in headless mode. To launch Chrome in visible (headful) mode for debugging, set the `X_BROWSER_HEADFUL` environment variable: diff --git a/src/content/partials/browser-run/example-quick-action-binding.mdx b/src/content/partials/browser-run/example-quick-action-binding.mdx index 88fef42d510..452ec082e2d 100644 --- a/src/content/partials/browser-run/example-quick-action-binding.mdx +++ b/src/content/partials/browser-run/example-quick-action-binding.mdx @@ -74,7 +74,7 @@ This Worker uses the browser binding to take a screenshot of `example.com` and r #### 4. Test -Run `npx wrangler dev --remote` to test your Worker locally. +Run `npx wrangler dev` to test your Worker locally.