# chrome-aws-lambda: A Chromium Binary and Puppeteer Bridge for Serverless Runtimes

> This package bundles a Chromium binary for AWS Lambda and Google Cloud Functions, exposing a thin API to launch Puppeteer or Playwright without the usual installation pain. It solves a real packaging problem, but its version coupling and font handling deserve scrutiny.

**alixaxel/chrome-aws-lambda** — GitHub describes it as Chromium Binary for AWS Lambda and Google Cloud Functions. The repository metadata lists TypeScript as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/alixaxel/chrome-aws-lambda
- Stars: 3,285 · Forks: 292
- Language: TypeScript
- License: MIT
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/alixaxel-chrome-aws-lambda

## The packaging problem it actually solves

Running headless Chrome on AWS Lambda has always been awkward. The standard Puppeteer download fetches a Chromium binary at install time, which works on a laptop but often fails in a serverless deployment because the binary is too large, the wrong platform, or missing shared libraries. chrome-aws-lambda addresses this by shipping a prebuilt Chromium binary tailored for AWS Lambda and Google Cloud Functions. The README states that installing the package "will ship with appropriate binary for the latest stable release of puppeteer." That is the core value: you get a binary that is known to work in the serverless environment, and you avoid the common failure mode where Puppeteer's postinstall script tries to download a browser and fails. The intended audience is developers who already use Puppeteer or Playwright and need the same code to run in a Lambda function or a Cloud Function without fighting the environment.

## How the package is structured and what the API exposes

The package exposes a small set of properties and methods. The README lists them in a table. The key ones are args, which provides recommended Chromium flags; executablePath, a Promise that resolves to the path where the binary was extracted; headless, a boolean that is true on AWS Lambda or GCF; and puppeteer, which overloads the Puppeteer package. The font() method takes an absolute path or URL and provisions a custom font, returning its basename. The design is simple: you import the package, pass its args and executablePath to Puppeteer's launch, and it handles the rest. The executablePath is a Promise, which is an unusual choice; you must await it. That asynchronous extract step means the first call to launch incurs a delay, and it also means the binary is extracted to a writable directory, which on Lambda is typically /tmp. The README does not specify the exact extraction path, but the behavior is implied by the Promise. The package also provides a defaultViewport and a headless flag, which are sensible defaults for serverless rendering.

## Installation and runtime requirements from the README

The README gives clear installation steps. You run npm install chrome-aws-lambda --save-prod, and then you must also install puppeteer-core or puppeteer at a matching version. The example uses require('chrome-aws-lambda') and launches with chromium.puppeteer.launch, passing args, defaultViewport, executablePath, headless, and ignoreHTTPSErrors. For memory, the README says to allocate at least 512 MB, but recommends 1600 MB or more. That is a concrete operational constraint. The package also supports Playwright, with a separate example that uses playwright-core and passes the same args and executablePath. The README does not mention any build step or native compilation, which is a relief for Lambda deployments. However, it also does not specify which Node.js runtimes are supported beyond "all the currently supported AWS Lambda Node.js runtimes." That phrase is vague, but it suggests the package tracks the official runtime support window. The font() method is a no-op on non-serverless environments, which is a thoughtful touch to avoid polluting a local machine.

## Font provisioning: a real gap in the Lambda runtime

The README notes that Amazon Linux 2 Lambda runtime ships with no font faces. That is a genuine problem for rendering pages with text, because Chromium will render tofu boxes or fall back to a default. The package ships Open Sans, which covers Latin, Greek, and Cyrillic. For emoji rendering, you need Noto Color Emoji, and the README suggests calling font() with a URL or absolute path before launching Chromium. The method accepts a URL, and the README recommends a CDN like raw.githack.com or gitcdn.xyz. There is also an alternative: create a .fonts directory, place font files there, zip it, and upload it as an AWS Lambda Layer. That is a workable approach, but it requires you to manage a layer separately. The font() method is a no-op on non-serverless environments, which means you cannot test font provisioning locally without extra steps. This is a limitation: if you develop locally, you will not see the same font behavior as in production, and you may ship a Lambda that renders text incorrectly because you forgot to call font() or because the CDN is unreachable.

## The overloaded API and page hooks: convenience with a cost

Since version 8.0.0, the package offers an overloaded Puppeteer API. The README shows interfaces for Browser, BrowserContext, and Page with extra methods like defaultPage, newPage, block, clear, clickAndWaitForNavigation, and clickAndWaitForRequest. These are convenience methods that reduce boilerplate. For example, block() can filter requests by patterns, and clickAndWaitForNavigation() handles the common click-then-wait pattern. The page hooks feature lets you pass a hook function to defaultPage() or newPage(), and the hook runs automatically on each new page. The README gives an example of removing the "Headless" substring from the user agent. This is a nice ergonomic improvement, but it comes with a cost: you are now tied to the package's API, not just the binary. If the package changes its typings or method signatures, your code may break even if Puppeteer itself is stable. The README says the typings file contains general documentation, but the overloaded methods are not part of standard Puppeteer, so you must learn a new API surface. The package also bundles additional page hooks in /build/hooks, but the README does not list them, so you have to inspect the source to know what is available.

## Versioning: a tight coupling to Puppeteer's release cycle

The README states that the package is versioned based on the underlying Puppeteer minor version. The table maps Puppeteer versions to chrome-aws-lambda versions and Chromium revisions. The table is truncated in the material, but the pattern is clear: you must install a chrome-aws-lambda version that matches your Puppeteer version. If you use a newer Puppeteer than the package supports, the binary may be incompatible, and you may get cryptic errors. This is a significant constraint. Puppeteer releases frequently, and the README says the package usually updates within a few days, but that is not guaranteed. If you need a specific Chromium revision for security or compliance reasons, you cannot simply pin it; you must wait for the package to catch up or use a different approach. The versioning scheme also means that upgrading Puppeteer requires upgrading chrome-aws-lambda, and you must check the mapping table each time. The README mentions that you can install an older version of Chromium by looking at the Versioning section, but the details are truncated. This coupling is the main trade-off: you gain a prebuilt binary, but you lose control over the exact browser version.

## Limitations and failure modes to consider

The package is not a silver bullet. The first limitation is the executablePath Promise: if the extraction fails, your Lambda will fail, and the error may not be clear. The README does not describe error handling for the font() method or the executablePath Promise. If the CDN for fonts is down, the font() call will fail, and the README does not say whether it retries or throws. Another failure mode is memory: the README recommends 1600 MB, but many Lambda functions are configured with 512 MB or less. If you ignore the recommendation, Chromium may crash with an out-of-memory error. The package also assumes you are running on AWS Lambda or GCF; on other platforms, the headless property returns false, and the font() method is a no-op, which could surprise you if you test locally and then deploy. The overloaded API adds methods that are not standard Puppeteer, so if you rely on them, you are locked into this package's implementation. If the package stops being maintained, you would have to fork it or migrate. The README does not mention any security patches for the Chromium binary, so you must trust that the package updates promptly when a vulnerability is disclosed.

## Alternatives and how they differ in approach

The primary alternative is to build your own Chromium layer or use a community layer like the one from the serverless-chrome project. The difference is in the build process. chrome-aws-lambda ships a prebuilt binary as part of the npm package, which is simple to install. A custom layer requires you to download the Chromium binary, strip it down, package it into a ZIP, and upload it as a Lambda layer. That approach gives you full control over the Chromium version and allows you to include only the files you need, which can reduce the deployment size. Another alternative is to use Puppeteer's own browser download and then copy the binary into your deployment, but that often fails on Lambda due to missing dependencies. The serverless-chrome project, for example, provides a prebuilt binary that you can use as a layer, but it is not tied to a specific Puppeteer version, so you must match it manually. The key difference is that chrome-aws-lambda handles the version matching for you, while a custom layer requires you to manage that yourself. If you need a specific Chromium revision, a custom layer is the better choice. If you want minimal effort and can accept the package's version cadence, chrome-aws-lambda is more convenient.

## Maintenance, licensing, and what to verify before adopting

The repository is MIT-licensed, which is permissive and allows commercial use without restrictions, though you should read the license file for exact terms. The project is not archived, and the primary language is TypeScript, which suggests active development, but the last push date is unknown in the provided material. The README mentions that the binary is updated within a few days of a Puppeteer release, so maintenance is largely driven by Puppeteer's schedule. You should verify the version mapping table on the repository's Versioning section before installing, because the README is truncated. You should also check the repository's issue tracker for known problems with your specific Lambda runtime (e.g., Node 18 or 20). The package has a wiki page for local development, which you should consult if you run into issues. Before adopting, test the font() method with your own fonts and a CDN to ensure it works in your environment. Also verify that the overloaded API methods you plan to use are present in the version you install, since the typings file is the source of truth. The maintenance cost is moderate: you must update the package whenever you upgrade Puppeteer, and you must test your Lambda function after each update.

## Conclusion

Adopt chrome-aws-lambda if you run Puppeteer or Playwright on AWS Lambda or Google Cloud Functions and want a prebuilt Chromium binary without compiling or downloading at runtime. Avoid it if you need a Chromium version that diverges from the latest Puppeteer minor release, or if you must control the exact revision for security compliance. Before adopting, verify the version mapping table for your target Puppeteer version, test the font() method on your specific runtime, and confirm that the overloaded Page methods cover your use cases. The package is MIT-licensed and actively maintained, but the tight coupling to Puppeteer's release cycle means you must plan upgrades carefully. If your workloads are simple page renders, this package is a practical shortcut; if you need custom Chromium flags or frequent version pinning, consider building your own layer.

## FAQ

### what is chrome aws lambda

A package that ships a Chromium binary built for AWS Lambda and Google Cloud Functions, plus the launch flags those sandboxes need. It exports `args`, `headless`, `defaultViewport`, `executablePath`, a `font()` method and an overloaded `puppeteer`, and you install the matching `puppeteer-core` yourself.

### How do I install chrome-aws-lambda and its browser client?

Two commands. Run `npm install chrome-aws-lambda --save-prod`, then install the corresponding version yourself with `npm install puppeteer-core --save-prod`. Older Chromium versions are reached through the package's versioning scheme, which tracks the puppeteer minor version.

### Which Puppeteer version does chrome-aws-lambda 10.1.0 match?

The package is versioned on the underlying puppeteer minor version, and this release is 10.1.0. `puppeteer-core` is declared as a peer dependency at ^10.1.0 and as a devDependency at the same range, so your project has to be on that generation for the package to work as intended.

### Does chrome-aws-lambda include fonts for rendering?

It ships Open Sans, covering Latin, Greek and Cyrillic, because the Amazon Linux 2 Lambda runtime is no longer provisioned with font faces. Anything else is added with the `font()` method, which must be awaited before Chromium launches, or shipped through a Lambda Layer containing a `.fonts` directory.

### Does chrome-aws-lambda work with Playwright as well as Puppeteer?

Yes, alongside `playwright-core`. The launch call takes `chromium.args`, `chromium.executablePath` and `chromium.headless`, and the example closes the browser with `browser.close()`, which the Puppeteer example in the same file does not show.

## Sources

- [Official README](https://github.com/alixaxel/chrome-aws-lambda#readme)
- [Project repository](https://github.com/alixaxel/chrome-aws-lambda)
- [README](https://github.com/alixaxel/chrome-aws-lambda/blob/master/README.md)
- [Releases](https://github.com/alixaxel/chrome-aws-lambda/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alixaxel-chrome-aws-lambda