browserless

browserless is a high-level wrapper on top of Puppeteer for reliable headless Chrome workflows.

Quick Start

Install

npm install browserless puppeteer

Minimal API usage

const createBrowser = require('browserless')
const { writeFile } = require('node:fs/promises')

const browser = createBrowser({ timeout: 30000 })
const browserless = await browser.createContext({ retry: 2 })

const screenshot = await browserless.screenshot('https://example.com')
await writeFile('screenshot.png', screenshot)

await browserless.destroyContext()
await browser.close()

When To Use What

• Use the API for reusable scripts, backend jobs, and multi-step browser flows.
• Use @browserless/cli for one-off terminal commands and quick checks.
• Use @browserless/lighthouse only when the task needs Lighthouse reports.

CLI Commands

Install once:

npm install -g @browserless/cli

Common commands:

• browserless screenshot <url>
• browserless pdf <url>
• browserless html <url>
• browserless text <url>
• browserless status <url>
• browserless ping <url>
• browserless goto <url>
• browserless page-weight <url>
• browserless lighthouse <url> (requires npm install -g @browserless/lighthouse)

Core API Patterns

Capture screenshot

const buffer = await browserless.screenshot('https://example.com', {
  device: 'iPhone 6',
  waitUntil: 'auto'
})

Generate PDF

const buffer = await browserless.pdf('https://example.com', {
  margin: '0.35cm',
  printBackground: true
})

Extract rendered content

const html = await browserless.html('https://example.com')
const text = await browserless.text('https://example.com')

Custom evaluation

const getTitle = browserless.evaluate(page =>
  page.evaluate(() => document.title)
)

const title = await getTitle('https://example.com')

Reliability Rules

• Always call destroyContext() after each task and close() before process exit.
• Keep one browser process and create multiple contexts instead of launching many browsers.
• Start with defaults, then tune timeout, waitUntil, waitForSelector, and retry.
• If output is missing due blocked third-party scripts, retry with adblock: false.
• Set DEBUG=browserless to inspect internal navigation and request handling.

Related Packages

• browserless: core API.
• @browserless/cli: command-line interface.
• @browserless/lighthouse: Lighthouse reports.
• @browserless/screencast: frame-by-frame capture.
• @browserless/function: sandboxed code execution against a page.