Skip to main content
Version: v2

Quick Start

Welcome to the quick-start! Below are the top two integration we support, with quick directions on getting up and running with popular methods. See the sidebar for all the other supported API's and REST methods!

Choose your library

Using Puppeteer

Whether you're looking to get started, or already have an established codebase, browserless aims to make the transition as easy as possible. At a high-level, you'll need to do the following:

1. Install puppeteer

If you haven't chosen a library yet we highly recommend puppeteer as it's fairly active and has many maintainers. It's also built by the developers of Chrome, so it's one of the highest quality libraries around.

Installing puppeteer

$ npm i --save puppeteer
# or
> yarn add puppeteer

In development you'll likely want to install puppeteer's bundled version of Chromium, however you won't need this in production as Chrome is all taken care of for you by browserless. To disable the downloading of puppeteer, simply add an environment variable when installing:

Install for production

# Linux
$ PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
# Windows
set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

$ npm install --production
# or yarn install --production

You can read more about puppeteer's environment variables here.

2. Setup your app

As an example let's write a screenshot service that takes a picture of the website and downloads it. We'll setup a route on the /image path and take a picture of a static webpage (though you can make this configurable if you wish):

Screenshot service

import express from "express";
import puppeteer from "puppeteer";

const app = express();

app.get("/image", async (req, res) => {
let browser = null;

await puppeteer
.launch()
.then(async (browser) => {
const page = await browser.newPage();
await page.goto("http://www.example.com/");
const screenshot = await page.screenshot();
res.end(screenshot, "binary");
})
.catch((error) => {
if (!res.headersSent) {
res.status(400).send(error.message);
}
})
.finally(() => browser && browser.close());
});

app.listen(8080, () => console.log("Listening on PORT: 8080"));

With that in place, let's re-work some of our functionality to use browserless in production.

3. Update your app to use browserless

Once we have browserless account setup, or have it running via docker, we can simply "connect" to it in our application instead of launching Chrome.

warning

It's very important to close the browser for unit-based, otherwise you'll spend seconds on the browser running. The best practice is to implement try/catch blocks and set a custom timeout to last less than the 15 minute global timeout set by default, per your requirements.

Screenshot service with browserless

import express from "express";
import puppeteer from "puppeteer";

const IS_PRODUCTION = process.env.NODE_ENV === "production";
const browserWSEndpoint = "https://production-sfo.browserless.io?token=GOES-HERE";
const app = express();

const getBrowser = async () =>
IS_PRODUCTION ? puppeteer.connect({ browserWSEndpoint }) : puppeteer.launch();

app.get("/image", async (req, res) => {
let browser = null;

await getBrowser()
.then(async (browser) => {
const page = await browser.newPage();
await page.goto("http://www.example.com/");
const screenshot = await page.screenshot();
res.end(screenshot, "binary");
})
.catch((error) => {
if (!res.headersSent) {
res.status(400).send(error.message);
}
})
.finally(() => browser && browser.close());
});

app.listen(8080, () => console.log("Listening on PORT: 8080"));

That's it! Now you don't have to worry about bundling Chrome or it's dependencies in production and can continue to develop your application.

Below is a sample cURL call that will use your new service to ensure it's all working:

$ curl -X GET -o temp.png http://localhost:8080/image

What's next?

There's a lot more that you can configure and tune in browserless to handle the needs of your application. Be sure to read about all the options it exposes and how to get the most out of browserless.