@sparticuz/chromium

@sparticuz/chromium packages a headless-shell build of Chromium as brotli-compressed archives, plus the glue code to decompress and launch it correctly inside AWS Lambda, Vercel Functions, Netlify Functions, and other constrained serverless containers. Rather than bundling a system Chrome install (which serverless platforms don’t provide), the package ships the binary itself alongside fonts, SwiftShader (for software WebGL), and Amazon Linux 2023 compatibility libraries, wiring up LD_LIBRARY_PATH, HOME, and FONTCONFIG_PATH automatically based on runtime detection.

Because the project tracks Chromium’s own release cadence rather than semantic versioning, consumers pin a package version to the Puppeteer/Playwright Chromium revision they need. A companion -min variant omits the ~50MB binary from the npm package itself, instead downloading a chromium-pack tarball from a URL or Lambda layer at cold start — useful for platforms with strict deployment-size limits. The package deliberately stays out of Puppeteer/Playwright version-pinning concerns, exposing only the binary, a recommended args array of Chromium command-line flags tuned for headless server-side rendering, and an executablePath() resolver.

What You Get

• A prebuilt, brotli-compressed Chromium headless-shell binary for x64 (arm64 available via GitHub release layer/pack assets)
• chromium.args — a maintained list of Chromium CLI flags for serverless (no-sandbox, single-process, disabled site isolation, optional WebGL via SwiftShader)
• chromium.executablePath() — resolves, downloads (if given a URL), and decompresses the binary to /tmp on first cold start, then reuses it on warm starts
• Automatic environment setup (LD_LIBRARY_PATH, HOME, FONTCONFIG_PATH) for AWS Lambda, Vercel, Netlify, and CodeBuild, including Amazon Linux 2023 detection
• A -min sibling package for platforms with strict package-size limits, supporting Lambda layers or a remotely hosted pack tarball

Common Use Cases

• Generating PDFs or screenshots of web pages from an AWS Lambda function via Puppeteer or Playwright
• Scraping or rendering JavaScript-heavy pages inside a Vercel or Netlify serverless function
• Running headless-browser visual regression or automated QA checks from a CI job without a container image
• Server-side rendering or link-preview generation triggered by an API Gateway or edge function invocation

Under The Hood

Architecture The public surface is a single static-method Chromium class in source/index.ts that acts as a thin orchestration layer over three focused helper modules: helper.ts (network downloads, environment-variable setup, URL/runtime detection), lambdafs.ts (streaming brotli/gzip/tar decompression via inflate()), and paths.ts (resolving the package’s own bin/ directory from the ESM module URL). executablePath() is the only meaningfully complex function: it short-circuits if /tmp/chromium already exists (warm start), recurses into itself if given a remote URL (delegating to downloadAndExtract() first), then runs the brotli/tar extractions for the binary, fonts, SwiftShader, and conditionally AL2023 libraries in parallel via Promise.all. Because nearly every consumer touches only args and executablePath(), changing either’s contract would break every downstream Puppeteer/Playwright integration that depends on this package.

Tech Stack Written in TypeScript targeting Node 22+/24 as native ESM ("type": "module"), with a single runtime dependency, tar-fs, for tar extraction — everything else (fetch, brotli, zlib) comes from Node’s own APIs. The devDependency set (@tsconfig/strictest, typescript-eslint, @sparticuz/eslint-config, prettier, vitest, @vitest/coverage-v8) reflects a strict, lint-and-test-gated workflow. Distribution is unusual for an npm package: actual Chromium binaries are compiled and brotli-compressed by a dedicated EC2-based GitHub Actions pipeline (build-chromium.yml) per architecture (x64/arm64), then published both as npm-bundled .br archives and as separate Lambda-layer zips / pack tarballs attached to GitHub releases, with a Makefile driving the packaging and layer-zip assembly.

Code Quality Testing uses Vitest with real assertions rather than mocks where practical: helper functions are exercised against a local HTTP server for downloadFile/downloadAndExtract, and a separate “Integration” suite actually launches Chromium via puppeteer-core, navigates to live pages, and asserts against SHA-256 hashes of rendered screenshots — a notably rigorous approach for a package this size. Error handling is explicit throughout (status-code checks on fetch responses, a TypeError guard on setGraphicsMode, cleanup of partial extractions on failure), and ESLint/Prettier plus multiple CI workflows (test, release, build-chromium, check-chromium-update) enforce quality and keep the bundled Chromium version current automatically.

What Makes It Unique The project’s core value is operational rather than algorithmic: it tracks Chromium’s own release cadence (not semver) so a pinned version maps directly to a known Puppeteer/Playwright-compatible revision, ships a curated flag set empirically tuned to avoid Lambda-specific sandboxing and single-process crashes, and automatically detects which serverless runtime it’s in (Lambda, Vercel, Netlify, CodeBuild, Amazon Linux 2023) to wire up library paths without configuration. The companion -min package and remote pack-download path extend this to platforms with strict deployment-size ceilings, a constraint most general-purpose browser-automation libraries don’t address at all.