README.md

serverless-chrome

Serverless Chrome contains everything you need to get started running headless Chrome on AWS Lambda (possibly Azure and GCP Functions soon).

The aim of this project is to provide the scaffolding for using Headless Chrome during a serverless function invocation. Serverless Chrome takes care of building and bundling the Chrome binaries and making sure Chrome is running when your serverless function executes. In addition, this project also provides a few example services for common patterns (e.g. taking a screenshot of a page, printing to PDF, some scraping, etc.)

Why? Because it's neat. It also opens up interesting possibilities for using the Chrome DevTools Protocol (and tools like Chromeless or Puppeteer) in serverless architectures and doing testing/CI, web-scraping, pre-rendering, etc.

Contents

1. Quick Start
2. The Project
3. Examples
4. Documentation & Resources
   1. Building Headless Chrome/Chromium
5. Testing
6. Articles & Tutorials
7. Troubleshooting
8. Roadmap
9. Projects & Companies using serverless-chrome
10. Change log
11. Contributing
12. Prior Art
13. License

Quick Start

"Bla bla bla! I just want to start coding!" No problem:

Using AWS Lambda, the quickest way to get started is with the Serverless-framework CLI.

First, install serverless globally (npm install -g serverless) and then:

serverless create -u https://github.com/adieuadieu/serverless-chrome/tree/master/examples/serverless-framework/aws

Then, you must configure your AWS credentials either by defining AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environmental variables, or using an AWS profile. You can read more about this on the Serverless Credentials Guide.

In short, either:

export AWS_PROFILE=<your-profile-name>

or

export AWS_ACCESS_KEY_ID=<your-key-here>
export AWS_SECRET_ACCESS_KEY=<your-secret-key-here>

Then, to deploy the service and all of its functions:

npm run deploy

Further details are available in the Serverless Lambda example.

The Project

This project contains:

• @serverless-chrome/lambda NPM package
  A standalone module for AWS Lambda which bundles and launches Headless Chrome with support for local development. For use with—but not limited to—tools like Apex, Claudia.js, SAM Local, or Serverless.
• serverless-plugin-chrome NPM package
  A plugin for Serverless-framework services which takes care of everything for you. You just write the code to drive Chrome.
• Example functions
  • Serverless-framework AWS Lambda Node.js functions using serverless-plugin-chrome
• Build Automation & CI/CD
  Build and release tooling shell scripts and Dockerfile for automating the build/release of headless Chrome for serverless environments (AWS Lambda).

Examples

A collection of example functions for different providers and frameworks.

Serverless-framework

• Serverless-framework Some simple functions for the Serverless-framework on AWS Lambda. It includes the following example functions:

  • Print to PDF
  • Capture Screenshot
  • Page-load Request Logger

Documentation & Resources

Building Headless Chrome/Chromium

• Automated, regularly prebuilt binaries can be found on the Releases page 😎
• adieuadieu/headless-chromium-for-aws-lambda Docker image
• Documentation on building your own binaries
• Medium article on how to do build from scratch. This was the origin of this project.

Testing

Test with npm test. Each package also contains it's own integration tests which can be run with npm run test:integration.

Articles & Tutorials

A collection of articles and tutorials written by others on using serverless-chrome

• AWS DevOps Blog — UI Testing at Scale with AWS Lambda
• Running puppeteer and headless chrome on AWS lambda with Serverless
• Will it blend? Or how to run Google Chrome in AWS Lambda
• Running Selenium and Headless Chrome on AWS Lambda
• AWS Lambda上のheadless chromeをPythonで動かす
• AWS Lambda上でpuppeteerを動かして、スクレイピングする
• serverless-chrome で日本語を表示できるようにする

Troubleshooting

Can't get Selenium / ChromeDriver to work

Make sure that the versions of serverless-chrome, chromedriver, and Selenium are compatible. More details in [#133](#133 (comment)).

Roadmap

1.1

1. Support for Google Cloud Functions
2. Example for Apex
3. Example for Claudia.js

1.2

1. DOM manipulation and scraping example handler

Future

1. Support for Azure Functions
2. Headless Firefox

Projects & Companies using serverless-chrome

Tell us about your project on the Wiki!

Change log

See the CHANGELOG

Contributing

OMG. Yes. Plz, halp meeee.

Prior Art

This project was inspired in various ways by the following projects:

• PhantomJS
• wkhtmltopdf
• node-webkitgtk
• electron-pdf

License

serverless-chrome © Marco Lüthy. Released under the MIT license.
Authored and maintained by Marco Lüthy with help from contributors.

github.com/adieuadieu · GitHub @adieuadieu · Twitter @adieuadieu · Medium @marco.luethy