Skip to content
browserherdDocs
Integration

Connect with Puppeteer.

Use Puppeteer Core to control a managed Browserherd Chromium session. Connect through browserWSEndpoint, then use standard Puppeteer page operations.

Install Puppeteer Core

puppeteer-core is the lightweight package intended for connecting to an existing browser.

TERMINAL
npm install puppeteer-core

Connect to Browserherd

JAVASCRIPT · PUPPETEER
import puppeteer from "puppeteer-core";

const query = new URLSearchParams({
  token: process.env.BROWSERHERD_API_KEY,
  sessionTTL: "900",
  region: "us-east-1",
  sessionRecording: "true"
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://connect.browserherd.com?${query}`,
  defaultViewport: null
});

const page = await browser.newPage();
await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
The session appears in Browserherd History as soon as the WebSocket connection opens.

Practical examples

Navigate and extract content

JAVASCRIPT
const page = await browser.newPage();
await page.goto("https://example.com", {
  waitUntil: "networkidle2",
  timeout: 60_000
});

const result = await page.evaluate(() => ({
  title: document.title,
  heading: document.querySelector("h1")?.textContent,
  html: document.documentElement.outerHTML
}));

console.log(result);

Capture a screenshot

JAVASCRIPT
await page.setViewport({ width: 1440, height: 900 });
await page.goto("https://example.com");
await page.screenshot({
  path: "example.png",
  fullPage: true
});

Click and type

JAVASCRIPT
await page.waitForSelector("input[name=email]");
await page.type("input[name=email]", "[email protected]");
await page.click("button[type=submit]");
await page.waitForNavigation({ waitUntil: "networkidle2" });

Attach a persistent profile

Set profileId when the session should start with browser state previously saved in Browserherd.

JAVASCRIPT
const query = new URLSearchParams({
  token: process.env.BROWSERHERD_API_KEY,
  profileId: "profile_customer_demo",
  sessionTTL: "1800",
  sessionRecording: "true"
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://connect.browserherd.com?${query}`
});

Close sessions reliably

Close the browser even when a workflow fails. The configured session TTL is a safety limit, not a replacement for cleanup.

JAVASCRIPT
let browser;

try {
  browser = await puppeteer.connect({ browserWSEndpoint });
  await runWorkflow(browser);
} finally {
  await browser?.close();
}

Handle navigation timeouts

A page navigation timeout is separate from the Browserherd session TTL. Increase the page timeout when the destination is slow, while keeping a bounded session TTL for cost control.

JAVASCRIPT
page.setDefaultNavigationTimeout(60_000);
await page.goto(url, { waitUntil: "domcontentloaded" });