@sparticuz/chromium

Chromium for Serverless Platforms

sparticuz/chrome-aws-lambda was originally forked from alixaxel/chrome-aws-lambda#264.

The main difference, aside from the Chromium version, is the inclusion of some code from https://github.com/alixaxel/lambdafs, while removing it as a dependency. Due to changes in WebGL, the files in bin/swiftshader.tar.br must now be extracted to /tmp instead of /tmp/swiftshader. This required changes in lambdafs.

However, maintaining the package became difficult due to the rapid pace of puppeteer updates. @sparticuz/chromium is not tied to specific puppeteer versions and does not include the overrides and hooks found in the original package. It provides only Chromium, the code required to decompress the Brotli package, and a set of predefined arguments tailored for serverless environments.

Install

puppeteer ships with a preferred version of chromium. To determine which version of @sparticuz/chromium you need, visit the Puppeteer Chromium Support page.

For example, as of today, the latest version of puppeteer is 18.0.5, and the latest supported version of Chromium is 106.0.5249.0. Therefore, you should install @sparticuz/chromium@106.

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

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

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

If you need to install an older version of Chromium, see @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 release cycle, it does NOT follow semantic versioning. Breaking changes may occur at the 'patch' level. Please check the release notes for details on breaking changes.

Usage

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

import test from "node:test";
import puppeteer from "puppeteer-core";
import chromium from "@sparticuz/chromium";

// Optional: If you'd like to disable webgl, true is the default.
chromium.setGraphicsMode = false;

test("Check the page title of example.com", async (t) => {
  const viewport = {
    deviceScaleFactor: 1,
    hasTouch: false,
    height: 1080,
    isLandscape: true,
    isMobile: false,
    width: 1920,
  };
  const browser = await puppeteer.launch({
    args: await puppeteer.defaultArgs({ args: chromium.args, headless: "shell" }),
    defaultViewport: viewport,
    executablePath: await chromium.executablePath(),
    headless: "shell",
  });

  const page = await browser.newPage();
  await page.goto("https://example.com");
  const pageTitle = await page.title();
  await browser.close();

  t.assert.strictEqual(pageTitle, "Example Domain");
});

Usage with Playwright

import test from "node:test";
// Need to rename playwright's chromium object to something else
import { chromium as playwright } from "playwright-core";
import chromium from "@sparticuz/chromium";

test("Check the page title of example.com", async (t) => {
  const browser = await playwright.launch({
    args: chromium.args, // Playwright merges the args
    executablePath: await chromium.executablePath(),
    // headless: true, /* true is the default */
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto("https://example.com");
  const pageTitle = await page.title();
  await browser.close();

  t.assert.strictEqual(pageTitle, "Example Domain");
});

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. This is useful when your host has file size limits.

To use the -min package, install the @sparticuz/chromium-min package instead of @sparticuz/chromium

When using the -min package, you must specify the location of the Brotli files.

In this example, /opt/chromium contains all the Brotli files:

/opt
  /chromium
    /al2023.tar.br
    /chromium.br
    /fonts.tar.br
    /swiftshader.tar.br

const viewport = {
  deviceScaleFactor: 1,
  hasTouch: false,
  height: 1080,
  isLandscape: true,
  isMobile: false,
  width: 1920,
};
const browser = await puppeteer.launch({
  args: await puppeteer.defaultArgs({ args: chromium.args, headless: "shell" }),
  defaultViewport: viewport,
  executablePath: await chromium.executablePath("/opt/chromium"),
  headless: "shell",
});

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 close to your function's execution environment.

On the first run, @sparticuz/chromium will download the pack tar file, untar the files to /tmp/chromium-pack, and then decompress the chromium binary to /tmp/chromium. Subsequent runs (during a warm start) will detect that /tmp/chromium exists and use the already downloaded files.

The latest chromium-pack.arch.tar file is available in the latest release.

const viewport = {
  deviceScaleFactor: 1,
  hasTouch: false,
  height: 1080,
  isLandscape: true,
  isMobile: false,
  width: 1920,
};
const browser = await puppeteer.launch({
  args: await puppeteer.defaultArgs({ args: chromium.args, headless: "shell" }),
  defaultViewport: viewport,
  executablePath: await chromium.executablePath(
    "https://www.example.com/chromiumPack.tar",
  ),
  headless: "shell",
});

Examples

Here are some example projects and guides for 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 do not include a GUI. If you need to test your code using a headful instance, use your locally installed version of Chromium/Chrome, or the version provided by Puppeteer.

npx @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 environment variable such as IS_LOCAL, then use if/else statements to direct Puppeteer to the correct environment.

const viewport = {
  deviceScaleFactor: 1,
  hasTouch: false,
  height: 1080,
  isLandscape: true,
  isMobile: false,
  width: 1920,
};
const headlessType = process.env.IS_LOCAL ? false : "shell";
const browser = await puppeteer.launch({
  args:
    process.env.IS_LOCAL ?
      await puppeteer.defaultArgs()
    : await puppeteer.defaultArgs({ args: chromium.args, headless: headlessType }),
  defaultViewport: viewport,
  executablePath:
    process.env.IS_LOCAL ?
      "/tmp/localChromium/chromium/linux-1122391/chrome-linux/chrome"
    : await chromium.executablePath(),
  headless: headlessType,
});

macOS and Playwright

The Chromium binary included in this package is compiled for Linux only and will not work on macOS or Windows. For local development:

With Puppeteer: Set the IS_LOCAL environment variable and install Chrome or Chromium locally. The code example above demonstrates this pattern.

With Playwright: Install a local Chromium using Playwright's CLI, then configure your code to use it in local development:

import chromium from "@sparticuz/chromium";
import { chromium as playwright } from "playwright-core";

const isLocal = process.env.IS_LOCAL;

const browser = await playwright.launch({
  args: isLocal ? [] : chromium.args,
  executablePath:
    isLocal ?
      "/path/to/local/chromium" // e.g., from `npx playwright install chromium`
    : await chromium.executablePath(),
  headless: true,
});

To install Chromium locally via Playwright:

npx playwright install chromium

Bundler Configuration

When using a bundler (esbuild, webpack, rollup, etc.), @sparticuz/chromium must be marked as external. The package relies on relative path resolution to locate its binary files, which breaks when bundled.

esbuild

esbuild --bundle --external:@sparticuz/chromium index.js

Or if you want to externalize all packages:

esbuild --bundle --packages=external index.js

webpack

// webpack.config.js
module.exports = {
  externals: ["@sparticuz/chromium"],
  // ... rest of config
};

Serverless Framework (with serverless-esbuild)

# serverless.yml
custom:
  esbuild:
    external:
      - "@sparticuz/chromium"

If you see the error The input directory "/var/task/bin" does not exist, this almost certainly means the package was not externalized in your bundler configuration.

Frequently Asked Questions

Can I use ARM or Graviton instances?

YES! Starting at Chromium v135, arm64 binaries are available as a Lambda layer zip and a pack tar in each GitHub release.

Note: The npm package (@sparticuz/chromium) includes only x64 binaries. For arm64, use the @sparticuz/chromium-min package and then use one of these options:

• Lambda layer — download chromium-VERSION-layer.arm64.zip from the release and upload it as a Lambda layer
• Remote pack — host chromium-VERSION-pack.arm64.tar at an HTTPS URL and pass it to chromium.executablePath("https://example.com/chromium-pack.arm64.tar")

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

headless_shell is a purpose-built version of Chromium specifically for headless purposes. It does not include a GUI 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 dependency.

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

I'm experiencing timeouts or failures closing Chromium

This is a common issue. Chromium sometimes opens more pages than you expect. You can try the following:

for (const page of await browser.pages()) {
  await page.close();
}
await browser.close();

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

await 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 better to install Chromium and its dependencies from the distrib