Browser Backends

Feedstock supports three browser backends, configured via the backend field in BrowserConfig.

Playwright (Default)

Launches a local browser via Playwright. Supports Chromium, Firefox, and WebKit.

const crawler = new WebCrawler({
  config: {
    backend: { kind: "playwright" },
    browserType: "chromium", // or "firefox", "webkit"
    headless: true,
  },
});

Setup

bun add feedstock
bunx playwright install chromium

Generic CDP

Connect to any cloud browser provider — Browserbase, Browserless, or any service that exposes a Chrome DevTools Protocol WebSocket endpoint.

const crawler = new WebCrawler({
  config: {
    backend: {
      kind: "cdp",
      wsUrl: process.env.BROWSER_WS_URL!,
    },
  },
});

Under the hood this calls chromium.connectOverCDP(wsUrl) from Playwright, so you get the same Playwright Browser object as every other backend.

Lightpanda

Lightpanda is an AI-native headless browser built for speed. It connects via Chrome DevTools Protocol (CDP) and works as a drop-in replacement.

Local Mode

Launches a local Lightpanda process and connects via CDP.

bun add @lightpanda/browser

const crawler = new WebCrawler({
  config: {
    backend: {
      kind: "lightpanda",
      mode: "local",
      host: "127.0.0.1",  // optional, default
      port: 9222,          // optional, default
    },
  },
});

Cloud Mode

Connect to Lightpanda Cloud without installing anything locally.

const crawler = new WebCrawler({
  config: {
    backend: {
      kind: "lightpanda",
      mode: "cloud",
      token: process.env.LIGHTPANDA_TOKEN!,
      endpoint: "wss://euwest.cloud.lightpanda.io/ws", // optional, default
    },
  },
});

How It Works

All three backends produce a standard Playwright Browser object. The rest of the pipeline (page navigation, content capture, scraping, extraction) works identically regardless of which backend you choose.

Playwright backend:  launcher.launch() → Browser
Generic CDP:         chromium.connectOverCDP(wsUrl) → Browser
Lightpanda local:    lightpanda.serve() → chromium.connectOverCDP() → Browser
Lightpanda cloud:    chromium.connectOverCDP(wss://...) → Browser

All session management, page lifecycle, and cleanup is handled by the BrowserManager.

Connection Resilience

BrowserManager.start() retries on transient connection errors (ECONNREFUSED, ECONNRESET, ETIMEDOUT, EPIPE, WebSocket errors) with exponential backoff. By default it retries up to 3 times, starting at 500ms and doubling each attempt (capped at 30s). This is especially useful for CDP and Lightpanda Cloud backends where the remote endpoint may take a moment to become available.

// Override defaults if needed
await manager.start({ maxRetries: 5, baseDelayMs: 1000 });