Add Puppeteer support for Worker JavaScript and the worker shell

[scuffi]

Summary

This adds a public Puppeteer plugin for Computer's Worker JavaScript backend. The plugin bundles Cloudflare's Worker-compatible Puppeteer client, connects it to a Browser Run binding, and keeps Browser and Page objects inside each isolated execution.

It exposes bound launch() and withBrowser() helpers, keeps plugin bindings separate from caller environment values, and closes connection-bound browser sessions when work completes or an execution is disposed.

The worker shell reaches the same capability through an opt-in browser command, so a browser task is available from a command line as well as from a module.

Usage

Register the plugin on the backend, then import Puppeteer from code executed by Computer:

import { Workspace } from "@cloudflare/computer";
import { WorkerJavaScriptBackend } from "@cloudflare/computer/backends/worker-javascript";
import { puppeteer } from "@cloudflare/computer/plugins/puppeteer";

const workspace = new Workspace({
  storage: ctx.storage,
  backends: [new WorkerJavaScriptBackend({
    loader: env.LOADER,
    plugins: [puppeteer({ browser: env.BROWSER })],
  })],
});

using execution = await workspace.runtime.exec(`
  import { withBrowser } from "@cloudflare/puppeteer";

  export default ({ url }) => withBrowser(async (browser) => {
    const page = await browser.newPage();
    await page.goto(url);
    return { title: await page.title() };
  });
`, { input: { url: "https://example.com" } });

const result = await execution.result();

Shell usage

Add the command group to a worker shell backend in the same Workspace:

import { WorkerShellBackend } from "@cloudflare/computer/backends/worker-shell";
import browser from "@cloudflare/computer/shell/browser";

new WorkerShellBackend({
  loader: env.LOADER,
  workspace: { binding: "Agent", id: ctx.id.toString() },
  ctx,
  commands: [browser],
});

A task module is an ordinary module whose default export receives a live browser alongside the caller's input:

// /workspace/tasks/title.js
export default async ({ url, browser }) => {
  const page = await browser.newPage();
  await page.goto(url);
  return { title: await page.title() };
};

browser puppeteer --url https://example.com/ tasks/title.js
browser puppeteer --url https://example.com/ --stdin < tasks/title.js

The shell does not drive the browser itself. The command resolves the task from the Workspace, wraps it in the same withBrowser() entry shown above, and dispatches that entry into the JavaScript backend carrying the plugin, so Puppeteer stays in the isolate. It prints the task's return value as JSON and exits with the task's exit code. --timeout sets the execution budget, --input merges a JSON object into the task input, and a --url confines the session to that host, its subdomains, and common content delivery networks.

Because the task runs in the JavaScript backend, it can write to the Workspace through node:fs/promises, so a stored task can be named, rerun, and edited, and its output outlives the execution that produced it.

Browser rendering example

The new self-hosted example stores one browser task in the Workspace and runs it both ways, as a JavaScript module and as a shell command. Either path writes report.md, page.json, and screenshot.png to one Workspace directory from a single isolated execution.

The package and architecture documentation cover Browser Run setup, lifecycle, limits, plugin authoring, and the authority granted to browser-enabled backends.

[changeset-bot]

🦋 Changeset detected

Latest commit: fac6026

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/dofs	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Thanks for your interest in Cloudflare Computer.

This repository does not accept unsolicited pull requests. Please use one of the accepted contribution paths instead:

• Bug reports, regressions, and fix proposals: https://github.com/cloudflare/computer/issues/new/choose
• Feature requests, enhancements, and design proposals: https://github.com/cloudflare/computer/discussions

If a maintainer asked you to open this pull request, they can add the allow-pr label and reopen it.

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 0 new potential issues.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@148

commit: fac6026

[aron-cf]

This is awesome, I'd love to keep worker shell backend in similar parity with the js one. What do you think to adding a browser CLI tool that takes a pupetteer flag or something.

browser puppeteer --url http://example.com run.js
browser puppeteer --url <url> --stdin <run.js

Where run.js is has a global browser instance:

export default async ({ url, browser }) => {
    const page = await browser.newPage();
    await page.goto(url);
    return { title: await page.title() };
});

[devin-ai-integration]

Devin Review found 4 new potential issues.

[devin-ai-integration]

🔍 Source imports require generation first

The plugin imports ignored generated.ts. npm hooks create it, but source-based tooling that skips scripts cannot load this entrypoint.

---

Was this helpful? React with 👍 or 👎 to provide feedback.