@sparticuz/chromium

Chromium for Serverless platforms

sparticuz/chrome-aws-lambda was originally forked from alixaxel/chrome-aws-lambda#264. The biggest difference, besides the chromium version, is the inclusion of some code from https://github.com/alixaxel/lambdafs, as well as dropping that as a dependency. Due to some changes in WebGL, the files in bin/swiftshader.tar.br need to be extracted to /tmp instead of /tmp/swiftshader. This necessitated changes in lambdafs.

However, it quickly became difficult to maintain because of the pace of puppeteer updates. This package, @sparticuz/chromium, is not chained to puppeteer versions, but also does not include the overrides and hooks that the original package contained. It is only chromium, as well as the special code needed to decompress the brotli package, and a set of predefined arguments tailored to serverless usage.

Install

puppeteer ships with a preferred version of chromium. In order to figure out what version of @sparticuz/chromium you will need, please visit Puppeteer's Chromium Support page.

For example, as of today, the latest version of puppeteer is 18.0.5. The latest version of chromium stated on puppeteer's support page is 106.0.5249.0. So you need to install @sparticuz/chromium@106.

1# Puppeteer or Playwright is a production dependency
2npm install --save puppeteer-core@$PUPPETEER_VERSION
3# @sparticuz/chromium can be a DEV dependency IF YOU ARE USING A LAYER, if you are not using a layer, use as a production dependency!
4npm install --save-dev @sparticuz/chromium@$CHROMIUM_VERSION

If your vendor does not allow large deploys (chromium.br is 50+ MB), you'll need to host the chromium-v#-pack.tar separately and use the @sparticuz/chromium-min package.

1npm install --save @sparticuz/chromium-min@$CHROMIUM_VERSION

If you wish to install an older version of Chromium, take a look at @sparticuz/chrome-aws-lambda or @alixaxel/chrome-aws-lambda.

Versioning

The @sparticuz/chromium version schema is as follows: MajorChromiumVersion.MinorChromiumIncrement.@Sparticuz/chromiumPatchLevel

Because this package follows Chromium's releases, it does NOT follow semantic versioning. Breaking changes can occur with the 'patch' level. Please check the release notes for information on breaking changes.

Usage

This package works with all the currently supported AWS Lambda Node.js runtimes out of the box.

1const test = require("node:test");
2const puppeteer = require("puppeteer-core");
3const chromium = require("@sparticuz/chromium");
4
5// Optional: If you'd like to disable webgl, true is the default.
6chromium.setGraphicsMode = false;
7
8// Optional: Load any fonts you need. Open Sans is included by default in AWS Lambda instances
9await chromium.font(
10  "https://raw.githack.com/googlei18n/noto-emoji/master/fonts/NotoColorEmoji.ttf"
11);
12
13test("Check the page title of example.com", async (t) => {
14  const browser = await puppeteer.launch({
15    args: chromium.args,
16    defaultViewport: chromium.defaultViewport,
17    executablePath: await chromium.executablePath(),
18    headless: chromium.headless,
19  });
20
21  const page = await browser.newPage();
22  await page.goto("https://example.com");
23  const pageTitle = await page.title();
24  await browser.close();
25
26  assert.strictEqual(pageTitle, "Example Domain");
27});

Usage with Playwright

1const test = require("node:test");
2// Need to rename playwright's chromium object to something else
3const { chromium: playwright } = require("playwright-core");
4const chromium = require("@sparticuz/chromium");
5
6test("Check the page title of example.com", async (t) => {
7  const browser = await playwright.launch({
8    args: chromium.args,
9    executablePath: await chromium.executablePath(),
10    headless: chromium.headless,
11  });
12
13  const context = await browser.newContext();
14  const page = await context.newPage();
15  await page.goto("https://example.com");
16  const pageTitle = await page.title();
17  await browser.close();
18
19  assert.strictEqual(pageTitle, "Example Domain");
20});

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

-min package

The -min package DOES NOT include the chromium brotli files. There are a few instances where this is useful. Primarily, this is useful when your host has file size limits.

To use the -min package please install the @sparticuz/chromium-min package.

When using the -min package, you need to specify the location of the brotli files.

In this example, /opt/chromium contains all the brotli files

/opt
  /chromium
    /aws.tar.br
    /chromium.br
    /swiftshader.tar.br

1const browser = await puppeteer.launch({
2  args: chromium.args,
3  defaultViewport: chromium.defaultViewport,
4  executablePath: await chromium.executablePath("/opt/chromium"),
5  headless: chromium.headless,
6});

In the following example, https://www.example.com/chromiumPack.tar contains all the brotli files. Generally, this would be a location on S3, or another very fast downloadable location, that is in close proximity to your function's execution location.

On the initial iteration, @sparticuz/chromium will download the pack tar file, untar the files to /tmp/chromium-pack, then will un-brotli the chromium binary to /tmp/chromium. The following iterations will see that /tmp/chromium exists and will use the already downloaded files.

The latest chromium-pack.tar file will be on the latest release.

1const browser = await puppeteer.launch({
2  args: chromium.args,
3  defaultViewport: chromium.defaultViewport,
4  executablePath: await chromium.executablePath(
5    "https://www.example.com/chromiumPack.tar"
6  ),
7  headless: chromium.headless,
8});

Examples

Here are some example projects and help with other services

• Production Dependency
• Serverless Framework with Lambda Layer
• Serverless Framework with Pre-existing Lambda Layer
• Chromium-min
• AWS SAM
• Webpack
• Netlify

Running Locally & Headless/Headful mode

This version of chromium is built using the headless.gn build variables, which does not even include a GUI. Also, this package does not include an ARM version yet, which means it will not work on any M Series Apple products. If you need to test your code using a headful or ARM version, please use your locally installed version of chromium/chrome, or you may use the puppeteer provided version. Users have reported installing rosetta on MacOS will also work.

1npx @puppeteer/browsers install chromium@latest --path /tmp/localChromium

For more information on installing a specific version of chromium, check out @puppeteer/browsers.

For example, you can set your code to use an ENV variable such as IS_LOCAL, then use if/else statements to direct puppeteer to the correct environment.

1const browser = await puppeteer.launch({
2  args: process.env.IS_LOCAL ? puppeteer.defaultArgs() : chromium.args,
3  defaultViewport: chromium.defaultViewport,
4  executablePath: process.env.IS_LOCAL
5    ? "/tmp/localChromium/chromium/linux-1122391/chrome-linux/chrome"
6    : await chromium.executablePath(),
7  headless: process.env.IS_LOCAL ? false : chromium.headless,
8});

Frequently asked questions

Can I use ARM or Graviton instances?

At this point, @sparticuz/chromium does not support ARM.

• https://github.com/Sparticuz/chrome-aws-lambda/pull/11

Can I use Google Chrome or Chrome for Testing, what is chrome-headless-shell?

headless_shell is a purpose built version of chromium specific for headless purposes. It does not include the GUI at all and only works via remote debugging connection. This is what this package is built on.

• https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md
• https://source.chromium.org/chromium/chromium/src/+/main:headless/app/headless_shell.cc
• https://developer.chrome.com/blog/chrome-headless-shell

Can I use the "new" Headless mode?

From what I can tell, headless_shell does not seem to include support for the "new" headless mode.

It doesn't work with Webpack!?!

Try marking this package as an external.

• https://webpack.js.org/configuration/externals/

I'm experiencing timeouts or failures closing Chromium

This is a common issue. Chromium sometimes opens up more pages than you ask for. You can try the following

1for (const page of await browser.pages()) {
2  await page.close();
3}
4await browser.close();

You can also try the following if one of the calls is hanging for some reason.

1await Promise.race([browser.close(), browser.close(), browser.close()]);

Always await browser.close(), even if your script is returning an error.

BrowserContext isn't working properly (Target.closed)

You may not be able to create a new context, you can try to use the default context as seen in this patch: https://github.com/Sparticuz/chromium/issues/298

Do I need to use @sparticuz/chromium?

This package is designed to be run on a vanilla Lambda instance. If you are using a dockerfile to publish your code to Lambda, it may be a better idea to install chromium and it's dependencies from the distribution's repositories.

I need Accessible pdf files

This is due to the way @sparticuz/chromium is built. If you require accessible pdf's, you'll need to recompile chromium yourself with the following patch. You can then use that binary with @sparticuz/chromium-min.

Note: This will increase the time required to generate a PDF.

1diff --git a/_/ansible/plays/chromium.yml b/_/ansible/plays/chromium.yml
2index b42c740..49111d7 100644
3--- a/_/ansible/plays/chromium.yml
4+++ b/_/ansible/plays/chromium.yml
5@@ -249,8 +249,9 @@
6           blink_symbol_level = 0
7           dcheck_always_on = false
8           disable_histogram_support = false
9-          enable_basic_print_dialog = false
10           enable_basic_printing = true
11+          enable_pdf = true
12+          enable_tagged_pdf = true
13           enable_keystone_registration_framework = false
14           enable_linux_installer = false
15           enable_media_remoting = false

Fonts

The Amazon Linux 2 AWS Lambda runtime is not provisioned with any font faces.

Because of this, this package ships with Open Sans, which supports the following scripts:

• Latin
• Greek
• Cyrillic

To provision additional fonts, simply call the font() method with an absolute path or URL:

1await chromium.font("/var/task/fonts/NotoColorEmoji.ttf");
2// or
3await chromium.font(
4  "https://raw.githack.com/googlei18n/noto-emoji/master/fonts/NotoColorEmoji.ttf"
5);

Noto Color Emoji (or similar) is needed if you want to render emojis.

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

This method should be invoked before launching Chromium.

---

Alternatively, it's also possible to provision fonts via AWS Lambda Layers.

Simply create a directory named .fonts or fonts and place any font faces you want there:

.fonts
├── NotoColorEmoji.ttf
└── Roboto.ttf

Afterwards, you just need to ZIP the directory and upload it as a AWS Lambda Layer:

1zip -9 --filesync --move --recurse-paths fonts.zip fonts/

Font directories are specified inside of the fonts.conf file found inside of the bin/fonts.tar.br file. These are the default folders:

• /var/task/.fonts
• /var/task/fonts
• /opt/fonts
• /tmp/fonts

Graphics

By default, this package uses swiftshader/angle to do CPU acceleration for WebGL. This is the only known way to enable WebGL on a serverless platform. You can disable WebGL by setting chromium.setGraphiceMode = false; before launching Chromium. Disabling this will also skip the extract of the bin/swiftshader.tar.br file, which saves about a second of initial execution time. Disabling graphics is recommended if you know you are not using any WebGL.

API

Method / Property	Returns	Description
font(url)	Promise<string>	Provisions a custom font and returns its basename.
args	Array<string>	Provides a list of recommended additional Chromium flags.
defaultViewport	Object	Returns a sensible default viewport for serverless.
executablePath(location?: string)	Promise<string>	Returns the path the Chromium binary was extracted to.
headless	"shell"	Returns "shell" which is what chrome-headless-shell requires
setGraphicsMode	void	Sets the graphics mode to either true or false
graphics	boolean	Returns a boolean depending on whether webgl is enabled or disabled

Compiling

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

AWS Lambda Layer

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

The following set of (Linux) commands will create a layer of this package:

1git clone --depth=1 https://github.com/sparticuz/chromium.git && \
2cd chromium && \
3make chromium.zip

The above will create a chromium.zip file, which can be uploaded to your Layers console. You can and should upload using the aws cli. (Replace the variables with your own values)

1bucketName="chromiumUploadBucket" && \
2versionNumber="107" && \
3aws s3 cp chromium.zip "s3://${bucketName}/chromiumLayers/chromium${versionNumber}.zip" && \
4aws lambda publish-layer-version --layer-name chromium --description "Chromium v${versionNumber}" --content "S3Bucket=${bucketName},S3Key=chromiumLayers/chromium${versionNumber}.zip" --compatible-runtimes nodejs --compatible-architectures x86_64

Alternatively, you can also download the layer artifact from one of our releases.

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

Migration from chrome-aws-lambda

• Change the import or require to be @sparticuz/chromium
• Add the import or require for puppeteer-core
• Change the browser launch to use the native puppeteer.launch() function
• Change the executablePath to be a function.

1-const chromium = require('@sparticuz/chrome-aws-lambda');
2+const chromium = require("@sparticuz/chromium");
3+const puppeteer = require("puppeteer-core");
4
5exports.handler = async (event, context, callback) => {
6  let result = null;
7  let browser = null;
8
9  try {
10-    browser = await chromium.puppeteer.launch({
11+    browser = await puppeteer.launch({
12      args: chromium.args,
13      defaultViewport: chromium.defaultViewport,
14-      executablePath: await chromium.executablePath,
15+      executablePath: await chromium.executablePath(),
16      headless: chromium.headless,
17      ignoreHTTPSErrors: true,
18    });
19
20    let page = await browser.newPage();
21
22    await page.goto(event.url || 'https://example.com');
23
24    result = await page.title();
25  } catch (error) {
26    return callback(error);
27  } finally {
28    if (browser !== null) {
29      await browser.close();
30    }
31  }
32
33  return callback(null, result);
34};

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

Backers

Thank you for your support!

Past

License

MIT