github.com/microlinkhq/browserless @v13.5.3 sqlite

The headless Chrome/Chromium driver on top of Puppeteer. - Highlights - Installation - Usage - The cloud API solution - CLI - Initializing a browser - .constructor(options) - .createContext(options) - .browser() - .respawn() - .close() - Built-in - .html(url, options) - .text(url, options) - .pdf(url, options) - .screenshot(url, options) - .destroyContext(options) - .getDevice(options) - .evaluate(fn, gotoOpts) - .goto(page, options) - .context() - .withPage(fn, [options]) - .page([name]) - Extended - function - lighthouse - screencast - Packages - FAQ - License

---

Highlights

• Compatible with Puppeteer API (text, screenshot, html, pdf).
• Built-in adblocker for canceling unnecessary requests.
• Shell interaction via Browserless CLI.
• Easy Google Lighthouse integration.
• Automatic retry & error handling.
• Sensible good defaults.

Installation

You can install it via npm:

npm install browserless puppeteer --save

Browserless runs on top of Puppeteer, so you need that installed to get started.

You can choose between puppeteer and puppeteer-core depending on your use case.

Usage

Here is a complete example showcasing some Browserless capabilities:

const createBrowser = require('browserless')
const termImg = require('term-img')

// First, create a browserless factory
// This is similar to opening a browser for the first time
const browser = createBrowser()

// Browser contexts are like browser tabs
// You can create as many as your resources can support
// Cookies/caches are limited to their respective browser contexts, just like browser tabs
const browserless = await browser.createContext()

// Perform your required browser actions.
// e.g., taking screenshots or fetching HTML markup
const buffer = await browserless.screenshot('http://example.com', {
  device: 'iPhone 6'
})

console.log(termImg(buffer))

// After your task is done, destroy your browser context
await browserless.destroyContext()

// At the end, gracefully shutdown the browser process
await browser.close()

As you can see, Browserless uses a single browser process, allowing you to create and destroy multiple browser contexts within that same process.

If you're already using Puppeteer in your project, you can layer Browserless on top simply by installing it.

You can also include additional Browserless packages to suit your specific needs, all of which work well with Puppeteer.

The cloud API solution

If you don’t want to manage that infrastructure, you can use the fully managed Microlink API.

It covers every browserless use case but automatically handles proxy rotation, paywalls, bot detection, and restricted platforms such as major social networks, while scaling on demand.

Pricing is pay-as-you-go and starts for free.

CLI

Using the Browserless command-line tool, you can interact with Browserless through a terminal window, or use it as part of an automated process:

Install @browserless/cli globally using your favorite package manager:

npm install -g @browserless/cli

Then run browserless in your terminal to see the list of available commands.

Initializing a browser

Initializing Browserless creates a headless browser instance.

const createBrowser = require('browserless')

const browser = createBrowser({
  timeout: 25000,
  lossyDeviceName: true,
  ignoreHTTPSErrors: true
})

This instance provides several high-level methods.

For example:

// Call `createContext` to create a browser tab
const browserless = await browser.createContext({ retry: 2 })

const buffer = await browserless.screenshot('https://example.com')

// Call `destroyContext` to close the browser tab.
await browserless.destroyContext()

The browser keeps running until you explicitly close it:

// At the end, gracefully shutdown the browser process
await browser.close()

.constructor(options)

The createBrowser method supports puppeteer.launch#options.

Browserless provides additional options for creating a browser instance:

defaultDevice

Sets your browser viewport to that of the specified device:

type: string

default: 'Macbook Pro 13'

lossyDeviceName

type: boolean

default: false

Allows for a margin of error when setting the device name.

// Initialize browser instance
const browser = require('browserless')({ lossyDeviceName: true });

(async () => {
    // Create context/tab
    const tabInstance = await browser.createContext();

    // Even if the device name is misspelled, the property will default to 'MacBook Pro'
    console.log(tabInstance.getDevice({ device: 'MacBook Pro' }))
    console.log(tabInstance.getDevice({ device: 'macbook pro 13' }))
    console.log(tabInstance.getDevice({ device: 'MACBOOK PRO 13' }))
    console.log(tabInstance.getDevice({ device: 'macbook pro' }))
    console.log(tabInstance.getDevice({ device: 'macboo pro' }))
})()

The provided name will be resolved to closest matching device.

This comes in handy in situations where the device name is set by a third-party.

mode

type: string

default: launch

values: 'launch' | 'connect'

Specifies if the browser instance should be spawned using puppeteer.launch or puppeteer.connect.

timeout

type: number

default: 30000

Changes the default maximum navigation time.

puppeteer

type: Puppeteer

default: puppeteer|puppeteer-core|puppeteer-firefox

By default, it automatically detects which libary is installed (thus either puppeteer or puppeteer-core based on your installed dependecies.

.createContext(options)

After initializing the browser, you can create a browser context which is equivalent to opening a tab:

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

Each browser context is isolated, thus cookies/cache stay within its corresponding browser contexts, just like browser tabs. Each context can be initialized with its own set of options.

options

All of Puppeteer's browser.createBrowserContext#options are supported.

Browserless provides additional browser context options:

retry

type: number

default: 2

The number of retries that can be performed before considering a navigation as failed.

.browser()

Returns the internal Browser instance.

const headlessBrowser = await browser.browser()

console.log('My headless browser PID is', headlessBrowser.process().pid)
console.log('My headless browser version is', await headlessBrowser.version())

.respawn()

Respawns the internal browser.

const getPID = promise => (await promise).process().pid

console.log('Process PID:', await getPID(browser.browser()))

await browser.respawn()

console.log('Process PID:', await getPID(browser.browser()))

This method is an implementation detail, normally you don't need to call it.

.close()

Closes the internal browser.

const { onExit } = require('signal-exit')
// automatically teardown resources after
// `process.exit` is called
onExit(browser.close)

Built-in

.html(url, options)

Serializes the content of a target url into HTML.

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

console.log(html)
// => "<!DOCTYPE html><html><head>…"

options

See browserless.goto for all the options and supported values.

.text(url, options)

Serializes the content from the target url into plain text.

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

console.log(text)
// => "Example Domain\nThis domain is for use in illustrative…"

options

See browserless.goto for all the options and supported values.

.pdf(url, options)

Generates the PDF version of a website behind a url.

const buffer = await browserless.pdf('https://example.com')

console.log(`PDF generated in ${buffer.byteLength()} bytes`)

options

This method uses the following options by default:

{
  margin: '0.35cm',
  printBackground: true,
  scale: 0.65
}

See browserless.goto for all the options and supported values.

Also, all of Puppeteer's page.pdf options are supported.

Additionally, you can setup:

margin

type: string | string[]

default: '0.35cm'

Sets screen margins. Supported units include:

• px for pixel.
• in for inches.
• cm for centimeters.
• mm for millimeters.

You can set the margin properties by passing them in as an object:

const buffer = await browserless.pdf(url.toString(), {
  margin: {
    top: '0.35cm',
    bottom: '0.35cm',
    left: '0.35cm',
    right: '0.35cm'
  }
})

In case a single margin value is provided, this will be used for all sides:

const buffer = await browserless.pdf(url.toString(), {
  margin: '0.35cm'
})

.screenshot(url, options)

Generates screenshots based on a specified url.

const buffer = await browserless.screenshot('https://example.com')

console.log(`Screenshot taken in ${buffer.byteLength()} bytes`)

options

This method uses the following options by default:

{
  device: 'macbook pro 13'
}

See browserless.goto for all the options and supported values.

Also, all of Puppeteer's page.screenshot options are supported.

Additionally, Browserless provides the following options:

codeScheme

type: string

default: 'atom-dark'

Whenever the incoming response 'Content-Type' is set to 'json', the JSON payload will be presented as a formatted JSON string, beautified using the provided codeScheme theme or by default atom-dark.

The color schemes is based on the Prism library.

The automad-prism-themes repository offers a wide range of themes to choose from as well as a CDN option.

element

type: string

Returns the first instance of a matching DOM element based on a CSS selector. This operation remains unresolved until the element is displayed on screen or the specified maximum timeout is reached.

overlay

type: object

Once the screenshot has been taken, this option allows you to apply an overlay (backdrop).

You can configure the overlay by specifying the following:

• browser: Specifies the color of the browser stencil to use, thus either light or dark for light and dark mode respectively.
• background: Specifies the background to use. A number of value types are supported:
• Hexadecimal/RGB/RGBA color codes, eg. #c1c1c1.
• CSS gradients, eg. linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)
• Image URLs, eg. `https://picsum.photos/1920/10