node package manager


Serverless-framework Headless Chrome Plugin

A Serverless-framework plugin which bundles the @serverless-chrome/lambda package and ensures that Headless Chrome is running when your function handler is invoked.



  1. Installation
  2. Setup
  3. Examples
  4. Local Development
  5. Configuration


Install with yarn:

yarn add --dev serverless-plugin-chrome

Install with npm:

npm install --save-dev serverless-plugin-chrome

Requires Node 6.10 runtime.


Add the following plugin to your serverless.yml:

  - serverless-plugin-chrome

Then, in your handler code.. Do whatever you want. Chrome will be running!

const CDP = require('chrome-remote-interface')
module.exports.hello = (event, context, callback, chrome) => {
  // Chrome is already running!
    .then((versionInfo) => {
      callback(null, {
        statusCode: 200,
        body: JSON.stringify({
    .catch((error) => {
      callback(null, {
        statusCode: 500,
        body: JSON.stringify({

Further details are available in the Serverless Lambda example.


Example functions are available here. They include:

  • Screenshot capturing handler: takes a picture of a URL
  • print-to-PDF handler: turns a URL into a PDF

Local Development

Local development is supported. You must install the chrome-launcher package in your project. A locally installed version of Chrome will be launched.

Command line flags (or "switches")

The behavior of Chrome does vary between platforms. It may be necessary to experiment with flags to get the results you desire. On Lambda default flags are used, but in development no default flags are used.


You can pass custom flags with which to launch Chrome using the custom section in serverless.yml. For example:

  - serverless-plugin-chrome
      - --window-size=1280x1696 # Letter size 
      - --hide-scrollbars
      - --ignore-certificate-errors
      - enableChromeOnThisFunctionName
      - mySuperChromeFunction

It is also possible to enable Chrome on only specific functions in your service using the configuration. For example:

      - enableChromeOnThisFunctionName
      - mySuperChromeFunction

You can enable debugging/logging output by specifying the DEBUG env variable in the provider section of serverless.yml. For example:

  name: aws
  runtime: nodejs6.10
    DEBUG: "*"
  - serverless-plugin-chrome

Using with other plugins

Load order is important.

For example, if you're using the serverless-webpack plugin, your plugin section should be:

  - serverless-plugin-chrome # 1st 
  - serverless-webpack

However, with the serverless-plugin-typescript plugin, the order is:

  - serverless-plugin-typescript
  - serverless-plugin-chrome # 2nd 


I keep getting a timeout error when deploying and it's really annoying.

Indeed, that is annoying. I've had the same problem, and so that's why it's now here in this troubleshooting section. This may be an issue in the underlying AWS SDK when using a slower Internet connection. Try changing the AWS_CLIENT_TIMEOUT environment variable to a higher value. For example, in your command prompt enter the following and try deploying again:

export AWS_CLIENT_TIMEOUT=3000000

Uuurrrggghhhhhh! Have you tried filing an Issue?