# sparticuz/chromium architecture

> Architecture diagram of the GitHub repository sparticuz/chromium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sparticuz/chromium
- Repository: https://github.com/sparticuz/chromium

## Overview

@sparticuz/chromium packages a serverless-ready Chromium runtime helper, not a browser automation framework. A consuming application obtains Chromium flags and an executable path, then gives both to Puppeteer or Playwright to launch Chromium. The package resolves bundled or caller-supplied assets, optionally downloads a remote pack, decompresses runtime files, and configures compatible Lambda environments. The README documents the -min remote-pack workflow and graphics controls; source excerpts show the implementation and its internal calls. The binary assets themselves are not present in the supplied tree, so they are represented only through the extraction component.

Main entry points: [`source/index.ts`](https://github.com/sparticuz/chromium/blob/master/source/index.ts) (Chromium API), [`source/helper.ts`](https://github.com/sparticuz/chromium/blob/master/source/helper.ts) (Pack Download), [`source/paths.ts`](https://github.com/sparticuz/chromium/blob/master/source/paths.ts) (Bundle Path), [`source/lambdafs.ts`](https://github.com/sparticuz/chromium/blob/master/source/lambdafs.ts) (Asset Decompression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Runtime API"]
  node_api["Chromium API<br/>[index.ts]"]
  node_flags["Launch Flags<br/>[index.ts]"]
  node_graphics["Graphics Mode<br/>[index.ts]"]
end

subgraph group_setup["Environment Setup"]
  node_environment["Lambda Environment<br/>[helper.ts]"]
end

subgraph group_assets["Asset Preparation"]
  node_path["Bundle Path<br/>[paths.ts]"]
  node_download["Pack Download<br/>[helper.ts]"]
  node_inflate["Asset Decompression<br/>[lambdafs.ts]"]
end

node_app(("Serverless App"))
node_puppeteer["Puppeteer / Playwright"]
node_browser["Headless Chromium"]
node_remote["Remote Pack"]

node_app -->|"requests runtime"| node_api
node_api -->|"configures environment"| node_environment
node_api -->|"resolves default path"| node_path
node_api -->|"downloads remote pack"| node_download
node_remote -.->|"provides archive"| node_download
node_api -->|"decompresses assets"| node_inflate
node_api -->|"provides launch flags"| node_flags
node_graphics -->|"controls graphics flags"| node_flags
node_app -->|"launches through"| node_puppeteer
node_flags -->|"supplies arguments"| node_puppeteer
node_api -->|"supplies executable path"| node_puppeteer
node_puppeteer -->|"launches"| node_browser

click node_api "https://github.com/sparticuz/chromium/blob/master/source/index.ts"
click node_flags "https://github.com/sparticuz/chromium/blob/master/source/index.ts"
click node_graphics "https://github.com/sparticuz/chromium/blob/master/source/index.ts"
click node_environment "https://github.com/sparticuz/chromium/blob/master/source/helper.ts"
click node_path "https://github.com/sparticuz/chromium/blob/master/source/paths.ts"
click node_download "https://github.com/sparticuz/chromium/blob/master/source/helper.ts"
click node_inflate "https://github.com/sparticuz/chromium/blob/master/source/lambdafs.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_flags,node_graphics toneBlue
class node_environment toneAmber
class node_path,node_download,node_inflate,node_app toneMint
class node_puppeteer,node_browser,node_remote toneIndigo
```

## Components

### Runtime API

- [Chromium API](https://github.com/sparticuz/chromium/blob/master/source/index.ts): `source/index.ts`
- [Launch Flags](https://github.com/sparticuz/chromium/blob/master/source/index.ts): `source/index.ts`
- [Graphics Mode](https://github.com/sparticuz/chromium/blob/master/source/index.ts): `source/index.ts`

### Environment Setup

- [Lambda Environment](https://github.com/sparticuz/chromium/blob/master/source/helper.ts): `source/helper.ts`

### Asset Preparation

- [Bundle Path](https://github.com/sparticuz/chromium/blob/master/source/paths.ts): `source/paths.ts`
- [Pack Download](https://github.com/sparticuz/chromium/blob/master/source/helper.ts): `source/helper.ts`
- [Asset Decompression](https://github.com/sparticuz/chromium/blob/master/source/lambdafs.ts): `source/lambdafs.ts`

### Other components

- **Serverless App**
- **Puppeteer / Playwright**
- **Headless Chromium**
- **Remote Pack**

## Connections

- Serverless App → Chromium API: requests runtime (evidence: `README.md`)
- Chromium API → Lambda Environment: configures environment (evidence: `source/index.ts`)
- Chromium API → Bundle Path: resolves default path (evidence: `source/index.ts`)
- Chromium API → Pack Download: downloads remote pack (evidence: `source/index.ts`)
- Remote Pack → Pack Download: provides archive (evidence: `README.md`)
- Chromium API → Asset Decompression: decompresses assets (evidence: `source/index.ts`)
- Chromium API → Launch Flags: provides launch flags (evidence: `README.md`)
- Graphics Mode → Launch Flags: controls graphics flags (evidence: `source/index.ts`)
- Serverless App → Puppeteer / Playwright: launches through (evidence: `README.md`)
- Launch Flags → Puppeteer / Playwright: supplies arguments (evidence: `README.md`)
- Chromium API → Puppeteer / Playwright: supplies executable path (evidence: `README.md`)
- Puppeteer / Playwright → Headless Chromium: launches (evidence: `README.md`)