Sparticuz/chromium for Serverless Browser Automation

Why Serverless Chromium Needs Its Own Packaging

Sparticuz/chromium addresses a packaging problem rather than replacing browser automation libraries. AWS Lambda functions cannot assume that a full desktop browser is already installed, and the Chromium version bundled by Puppeteer may not match the serverless runtime's deployment constraints. The package provides Chromium, code to decompress its Brotli archive, and predefined arguments tailored to serverless environments.

It is aimed at Node.js developers using `puppeteer-core` or `playwright-core`, especially those deploying to AWS Lambda Node.js runtimes. It does not provide a separate browser-control API. Puppeteer still creates pages, navigates to URLs, evaluates page content, and closes the browser. Playwright follows the same division, with the application supplying Playwright while this package supplies the executable path and launch arguments.

The project is intentionally independent of a particular Puppeteer release. The README says that it includes Chromium and serverless launch arguments, but not the overrides and hooks found in the original package from which its lineage began. That makes the dependency boundary narrower, although it also means applications should verify compatibility between the selected browser revision and their automation library.

Archive Extraction and Serverless Launch Flow

The main package includes Brotli files that contain Chromium and related assets. According to the README, the package extracts the files required by the runtime and exposes an executable path through `chromium.executablePath()`. The returned path is passed to `puppeteer.launch()` or `playwright.launch()`, which then starts the browser process.

For a normal deployment, the package can be installed as a production dependency. The README also says it can be a development dependency when the package contents are supplied through a Lambda layer. That distinction matters because a function without the layer needs the Chromium files available in its deployment artifact.

The WebGL configuration has one unusual filesystem requirement. The README states that files in `bin/swiftshader.tar.br` must be extracted to `/tmp`, not `/tmp/swiftshader`, because of changes in WebGL. The package incorporates code related to lambdafs to perform this extraction, while removing lambdafs as a separate dependency. Graphics mode can be disabled with `chromium.setGraphicsMode = false`, and the README identifies `true` as the default.

The package also defines `chromium.args`, a set of launch arguments intended for serverless execution. Puppeteer's example combines those arguments with `puppeteer.defaultArgs()`, while the Playwright example passes them directly because Playwright merges its own arguments.

Installing the Matching Browser Revision

The README does not treat the latest `@sparticuz/chromium` release as automatically correct for every automation library. It directs users to Puppeteer's Chromium support documentation because Puppeteer releases can require a particular Chromium version. The documented installation pattern uses environment variables for the Puppeteer and Chromium versions.

Install `puppeteer-core` as the production dependency. The README's example installs `@sparticuz/chromium` as a development dependency, with the stated exception that it must be a production dependency when no layer is used.

npm install --save puppeteer-core@$PUPPETEER_VERSION
npm install --save-dev @sparticuz/chromium@$CHROMIUM_VERSION

The version selection is a concrete compatibility decision. The package uses a Chromium-based version schema rather than ordinary semantic versioning. Its documentation warns that breaking changes can occur at the patch level, so changing package versions can require reading the release notes. A deployment process that updates Chromium independently of Puppeteer should preserve the selected package revision and verify the browser revision expected by the installed automation client.

For Playwright users, the repository documentation does not provide a separate Playwright installation command in the shown section. The usage example imports `chromium as playwright` from `playwright-core`, which indicates that the application must already have that client available. The executable and argument integration is documented, but the version compatibility procedure is not.

First Puppeteer Use with a Page Title Check

The following example is the project's first concrete Puppeteer use. It launches Chromium, opens `https://example.com`, reads the page title, closes the browser, and asserts that the title is `Example Domain`. The executable path is asynchronous because the package prepares or locates the browser before launch.

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

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");
});

The example uses `node:test`, but the package does not require that test runner for browser automation. The application can instead use Puppeteer from a normal function. The important integration points are `chromium.args`, `chromium.executablePath()`, and the headless launch mode.

The README recommends at least 512 MB of RAM and says that 1600 MB or more is recommended. That memory guidance is a platform constraint, not a promise about runtime performance. A function that launches multiple pages or concurrent browsers must account for the memory cost of each Chromium process.

Playwright Uses the Same Binary with a Different Merge Model

The Playwright example imports the package's executable provider and Playwright's Chromium launcher under different names. Playwright receives `chromium.args` directly, while the executable path comes from `await chromium.executablePath()`. The project states that Playwright merges the supplied arguments.

import test from "node:test";
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,
    executablePath: await chromium.executablePath(),
  });

  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");
});

The architecture is straightforward: `@sparticuz/chromium` does not own browser contexts, pages, or selectors. Those remain Playwright's responsibility. This makes it possible to swap the automation library while retaining the serverless binary package, provided the Chromium revision is accepted by that library.

The Playwright example omits an explicit `headless` setting because the comment says `true` is the default. That is a Playwright launch default described by the README, not a guarantee that every surrounding runtime configuration behaves identically.

Lambda Layers, the min Package, and Deployment Size

The normal package can be used as a development dependency when a Lambda layer contains the Chromium files. If the layer is not used, the README instructs users to make `@sparticuz/chromium` a production dependency. A layer-based deployment avoids placing the complete browser payload in the function package, but it introduces a separate packaging and versioning step.

Some hosting providers reject large deployments because `chromium.br` is over 50 MB. In that case, the project directs users to `@sparticuz/chromium-min`, which omits the Chromium Brotli files.

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

The min package requires an explicit location for the Brotli files. The README's local layout is:

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

The files can instead be hosted at a downloadable location. According to the README, the package downloads a pack tar file on the first run, extracts it to `/tmp/chromium-pack`, decompresses the Chromium binary to `/tmp/chromium`, and reuses the existing binary during a warm start. A fast location close to the function environment is recommended. This design trades a larger local deployment for startup download and extraction work, which can be a poor fit when cold-start latency matters.

Compatibility, Resource Limits, and Alternative Packaging

The clearest limitation is browser revision matching. Puppeteer documents a preferred Chromium version for each client release, while this package tracks Chromium's release cycle and warns that patch-level versions can contain breaking changes. An application cannot safely assume that the newest browser package is compatible with every Puppeteer or Playwright version.

The second limitation is deployment shape. A regular Node.js host can install and manage a system browser, so a serverless-specific package may add an unnecessary large binary and decompression step. Sparticuz/chromium is more relevant when the runtime has no suitable preinstalled Chromium or when the function must carry its own browser.

A real alternative is `@sparticuz/chrome-aws-lambda`, the project from which this repository originated as a fork. The README directs users needing older Chromium versions to that repository or to `alixaxel/chrome-aws-lambda`. The choice is not simply a feature comparison. The current package is organized around Chromium's release cycle and serverless extraction, while the older packages are relevant when a deployment needs an older browser revision.

Another approach is using the browser binary supplied by a host image or platform layer and controlling it with `puppeteer-core`. That avoids Sparticuz's packaging logic when the platform already provides a compatible browser, but it also requires the operator to maintain that image and keep its browser revision aligned with the automation client.

Maintenance Signals and Upgrade Work

The repository is not archived. Its last push was on 2026-10-07, so it can be described as recently pushed rather than actively maintained by implication. The release list includes `v153.0.0`, released on 2026-09-11, `v152.0.0`, released on 2026-09-08, and `v149.0.0`, released on 2026-05-27.

The project is licensed under the MIT license, according to `package.json`. That license identifier permits use and modification under its terms, but this review does not provide legal advice and does not replace the repository's `LICENSE` file.

Upgrade work is not limited to changing a version number. A team must review release notes because the package does not follow semantic versioning, then verify the Chromium version supported by its Puppeteer or Playwright release. A layer, `chromium.br`, `@sparticuz/chromium-min`, and a remotely hosted pack are separate deployment choices, each with its own file layout and startup implications. The repository contains examples for Lambda layers, remote min binaries, production dependencies, Graviton with a pack, preexisting layers, AWS SAM, and webpack, but the README does not claim that all of those deployment paths have identical behavior.

Editorial conclusion

Sparticuz/chromium is appropriate for Node.js teams running Puppeteer or Playwright in Lambda-sized environments that need a packaged or remotely supplied Chromium binary. It is less suitable for ordinary long-running hosts, deployments that reject its large artifact, or users who need Puppeteer-specific overrides and hooks. Verify the matching Chromium version, available memory, deployment size, binary location, and release notes before adoption.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Sparticuz/chromium on GitHub