chrome-aws-lambda

chrome-aws-lambda

Chromium Binary for AWS Lambda and Google Cloud Functions

Install

npm install chrome-aws-lambda --save-prod

This will ship with appropriate binary for the latest stable release of puppeteer (usually updated within a few days).

You will also need to install the corresponding version of puppeteer (or puppeteer-core):

npm install puppeteer-core --save-prod

If you wish to install an older version of Chromium, take a look at Versioning.

Usage

This package works with the nodejs8.10, nodejs10.x and nodejs12.x AWS Lambda runtimes out of the box.

const chromium = require('chrome-aws-lambda');

exports.handler = async (event, context, callback) => {
  let result = null;
  let browser = null;

  try {
    browser = await chromium.puppeteer.launch({
      args: chromium.args,
      defaultViewport: chromium.defaultViewport,
      executablePath: await chromium.executablePath,
      headless: chromium.headless,
      ignoreHTTPSErrors: true,
    });

    let page = await browser.newPage();

    await page.goto(event.url || 'https://example.com');

    result = await page.title();
  } catch (error) {
    return callback(error);
  } finally {
    if (browser !== null) {
      await browser.close();
    }
  }

  return callback(null, result);
};

You should allocate at least 512 MB of RAM to your Lambda, however 1600 MB (or more) is recommended.

Running Locally

Please refer to the Local Development Wiki page for instructions and troubleshooting.

API

Method / Property	Returns	Description
font(url)	{?Promise<string>}	Downloads a custom font and returns its basename.
args	{!Array<string>}	Provides a list of recommended additional Chromium flags.
defaultViewport	{!Object}	Returns more sensible default viewport settings.
executablePath	{?Promise<string>}	Returns the path where the Chromium binary was extracted.
headless	{!boolean}	Returns true if we are running on AWS Lambda or GCF.
puppeteer	{!Object}	Overloads puppeteer and returns the resolved package.

Fonts

Since version 1.12.2, the font() method will download additional fonts and make them discoverable.

To use it, simply pass a URL or local file path to a custom font face before launching Chromium, e.g.:

await chromium.font('https://raw.githack.com/googlei18n/noto-emoji/master/fonts/NotoColorEmoji.ttf');

The above font is needed if you want to render emojis.

Fonts with the same basename will only be downloaded if they are not already cached.

On non-serverless environments, the font() method is a no-op to avoid polluting the user space.

It's recommended that you use a CDN, like raw.githack.com or gitcdn.xyz.

---

As of version 3.0.4, the font() method will also work with local file paths and HTTP URLs.

Overloading

Since version 1.7.0, it's also possible to overload puppeteer / puppeteer-core API with useful methods:

• Frame
  • count(selector)
  • exists(selector)
  • fill(form, data, heuristic = 'name')
  • number(selector, decimal = null, index = null, property = 'textContent')
  • selectByLabel(selector, ...values)
  • string(selector, property = 'textContent')
  • waitUntilVisible(selector, timeout = null)
  • waitWhileVisible(selector, timeout = null)
• Page
  • clickAndWaitForNavigation(selector, options = null)
  • count(selector)
  • exists(selector)
  • fill(form, data, heuristic = 'name')
  • go(url, options = null)
  • number(selector, decimal = null, index = null, property = 'textContent')
  • selectByLabel(selector, ...values)
  • string(selector, property = 'textContent')
  • waitUntilVisible(selector, timeout = null)
  • waitWhileVisible(selector, timeout = null)

Since version 5.0.0 the number of overloads are further augmented:

• Browser
  • newPage(...hooks)
• Page
  • allow(...resources)
  • block(...resources)

Besides the public API, the following browser-context methods will also be available:

• σ.$(selector, context = document)
• σ.$$(selector, index = null, context = document)
• σ.$x(expression, index = null, context = document)
• σ.$number(data, decimal = null, index = null, property = 'textContent')
• σ.$string(data, property = 'textContent')
• σ.$regexp(data, pattern, index = null, property = 'textContent')

To enable overloading, simply call the puppeteer property exposed by this package.

New Page Hooks

Since version 5.0.0 you can specify a list of hooks to apply to created pages.

For instance, to enable ad-blocking (using @cliqz/adblocker-puppeteer):

const { fullLists, PuppeteerBlocker } = require('@cliqz/adblocker-puppeteer');
const { promises } = require('fs');

async function adblock(page) {
  const fetch = (url) => {
    let handler = url.startsWith('https://') ? require('https').get : require('http').get;

    return new Promise((resolve, reject) => {
      return handler(url, (response) => {
        if (response.statusCode !== 200) {
          return reject(`Unexpected status code: ${response.statusCode}.`);
        }

        let result = '';

        response.on('data', (chunk) => {
          result += chunk;
        });

        response.on('end', () => {
          return resolve({ text: () => result });
        });
      });
    });
  };

  await PuppeteerBlocker.fromLists(fetch, fullLists, { enableCompression: false }, {
    path: '/tmp/adblocker.bin',
    read: promises.readFile,
    write: promises.writeFile,
  }).then((blocker) => blocker.enableBlockingInPage(page));

  return page;
}

And then simply pass hooks hooks to newPage():

let page = await browser.newPage(adblock);

Versioning

This package is versioned based on the underlying puppeteer minor version:

puppeteer Version	chrome-aws-lambda Version	Chromium Revision
5.4.*	npm i chrome-aws-lambda@~5.4.0	809590 (87.0.4272.0)
5.3.*	npm i chrome-aws-lambda@~5.3.1	800071 (86.0.4240.0)
5.2.*	npm i chrome-aws-lambda@~5.2.1	782078 (85.0.4182.0)
5.1.*	npm i chrome-aws-lambda@~5.1.0	768783 (84.0.4147.0)
5.0.*	npm i chrome-aws-lambda@~5.0.0	756035 (83.0.4103.0)
3.1.*	npm i chrome-aws-lambda@~3.1.1	756035 (83.0.4103.0)
3.0.*	npm i chrome-aws-lambda@~3.0.4	737027 (81.0.4044.0)
2.1.*	npm i chrome-aws-lambda@~2.1.1	722234 (80.0.3987.0)
2.0.*	npm i chrome-aws-lambda@~2.0.2	705776 (79.0.3945.0)
1.20.*	npm i chrome-aws-lambda@~1.20.4	686378 (78.0.3882.0)
1.19.*	npm i chrome-aws-lambda@~1.19.0	674921 (77.0.3844.0)
1.18.*	npm i chrome-aws-lambda@~1.18.1	672088 (77.0.3835.0)
1.18.*	npm i chrome-aws-lambda@~1.18.0	669486 (77.0.3827.0)
1.17.*	npm i chrome-aws-lambda@~1.17.1	662092 (76.0.3803.0)
1.16.*	npm i chrome-aws-lambda@~1.16.1	656675 (76.0.3786.0)
1.15.*	npm i chrome-aws-lambda@~1.15.1	650583 (75.0.3765.0)
1.14.*	npm i chrome-aws-lambda@~1.14.0	641577 (75.0.3738.0)
1.13.*	npm i chrome-aws-lambda@~1.13.0	637110 (74.0.3723.0)
1.12.*	npm i chrome-aws-lambda@~1.12.2	624492 (73.0.3679.0)
1.11.*	npm i chrome-aws-lambda@~1.11.2	609904 (72.0.3618.0)
1.10.*	npm i chrome-aws-lambda@~1.10.1	604907 (72.0.3582.0)
1.9.*	npm i chrome-aws-lambda@~1.9.1	594312 (71.0.3563.0)
1.8.*	npm i chrome-aws-lambda@~1.8.0	588429 (71.0.3542.0)
1.7.*	npm i chrome-aws-lambda@~1.7.0	579032 (70.0.3508.0)
1.6.*	npm i chrome-aws-lambda@~1.6.3	575458 (69.0.3494.0)
1.5.*	npm i chrome-aws-lambda@~1.5.0	564778 (69.0.3452.0)
1.4.*	npm i chrome-aws-lambda@~1.4.0	555668 (68.0.3419.0)
1.3.*	npm i chrome-aws-lambda@~1.3.0	549031 (67.0.3391.0)
1.2.*	npm i chrome-aws-lambda@~1.2.0	543305 (67.0.3372.0)
1.1.*	npm i chrome-aws-lambda@~1.1.0	536395 (66.0.3347.0)
1.0.*	npm i chrome-aws-lambda@~1.0.0	526987 (65.0.3312.0)
0.13.*	npm i chrome-aws-lambda@~0.13.0	515411 (64.0.3264.0)

Compiling

To compile your own version of Chromium check the Ansible playbook instructions.

AWS Lambda Layer

Lambda Layers is a new convenient way to manage common dependencies between different Lambda Functions.

The following set of (Linux) commands will create a layer of this package alongside puppeteer-core:

git clone --depth=1 https://github.com/alixaxel/chrome-aws-lambda.git && \
cd chrome-aws-lambda && \
make chrome_aws_lambda.zip

The above will create a chrome-aws-lambda.zip file, which can be uploaded to your Layers console.

The folks @shelfio also maintain and publish AWS Lambda Layers of this package.

Google Cloud Functions

Since version 1.11.2, it's also possible to use this package on Google/Firebase Cloud Functions.

The only additional requirement is that iltorb must also be added as a dependency:

npm install iltorb --save-prod

According to our benchmarks, it's 40% to 50% faster than using the off-the-shelf puppeteer bundle.

Compression

The Chromium binary is compressed using the Brotli algorithm.

This allows us to get the best compression ratio and faster decompression times.

File	Algorithm	Level	Bytes	MiB	%	Inflation
chromium	-	-	136964856	130.62	-	-
chromium.gz	Gzip	1	51662087	49.27	62.28%	1.035s
chromium.gz	Gzip	2	50438352	48.10	63.17%	1.016s
chromium.gz	Gzip	3	49428459	47.14	63.91%	0.968s
chromium.gz	Gzip	4	47873978	45.66	65.05%	0.950s
chromium.gz	Gzip	5	46929422	44.76	65.74%	0.938s
chromium.gz	Gzip	6	46522529	44.37	66.03%	0.919s
chromium.gz	Gzip	7	46406406	44.26	66.12%	0.917s
chromium.gz	Gzip	8	46297917	44.15	66.20%	0.916s
chromium.gz	Gzip	9	46270972	44.13	66.22%	0.968s
chromium.gz	Zopfli	10	45089161	43.00	67.08%	0.919s
chromium.gz	Zopfli	20	45085868	43.00	67.08%	0.919s
chromium.gz	Zopfli	30	45085003	43.00	67.08%	0.925s
chromium.gz	Zopfli	40	45084328	43.00	67.08%	0.921s
chromium.gz	Zopfli	50	45084098	43.00	67.08%	0.935s
chromium.br	Brotli	0	55401211	52.83	59.55%	0.778s
chromium.br	Brotli	1	54429523	51.91	60.26%	0.757s
chromium.br	Brotli	2	46436126	44.28	66.10%	0.659s
chromium.br	Brotli	3	46122033	43.99	66.33%	0.616s
chromium.br	Brotli	4	45050239	42.96	67.11%	0.692s
chromium.br	Brotli	5	40813510	38.92	70.20%	0.598s
chromium.br	Brotli	6	40116951	38.26	70.71%	0.601s
chromium.br	Brotli	7	39302281	37.48	71.30%	0.615s
chromium.br	Brotli	8	39038303	37.23	71.50%	0.668s
chromium.br	Brotli	9	38853994	37.05	71.63%	0.673s
chromium.br	Brotli	10	36090087	34.42	73.65%	0.765s
chromium.br	Brotli	11	34820408	33.21	74.58%	0.712s

License

MIT