@sparticuz/chromium

The EC2 build instance itself requires an IAM role (via an instance profile) to upload build artifacts and logs to S3. This role does not need EC2 or SSM permissions, only S3 access.

1. Create the Role Policy: Use a policy that allows s3:PutObject, s3:GetObject, and s3:DeleteObject on your build bucket.
2. Attach Trust Policy: Ensure the role has a trust policy allowing ec2.amazonaws.com to assume the role.
3. Create and Associate Instance Profile: Use the AWS CLI to create the profile and link it to the role.

Required Permissions on EC2:

• s3:PutObject: Upload artifacts, build logs, and build.json.
• s3:DeleteObject: Remove pending.json during teardown or failure.
• s3:GetObject: Read/modify build.json to report progress.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3ArtifactUpload",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::BUCKET_NAME", "arn:aws:s3:::BUCKET_NAME/*"]
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "ec2.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

aws iam create-instance-profile --instance-profile-name chromium-build
aws iam add-role-to-instance-profile \
  --instance-profile-name chromium-build --role-name chromium-build

The -min package does not include the Chromium Brotli files. This is useful when your host has file size limits. When using it, you must provide the location of the Brotli files to chromium.executablePath().

Option 1: Local Path Provide a path to a directory containing the Brotli files (e.g., /opt/chromium).

Option 2: Remote URL Provide a URL to a .tar file containing the Brotli files. On the first run, the package will download the pack, untar it to /tmp/chromium-pack, and decompress the binary to /tmp/chromium. Subsequent warm starts will use the existing files in /tmp.

// Example using a local path
const browser = await puppeteer.launch({
  args: await puppeteer.defaultArgs({ args: chromium.args, headless: "shell" }),
  defaultViewport: viewport,
  executablePath: await chromium.executablePath("/opt/chromium"),
  headless: "shell",
});

// Example using a remote URL
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",
});

To allow the GitHub Actions runner to manage the EC2 build infrastructure (launching instances, managing security groups, and interacting with S3), create an IAM user (or use OIDC federation) with the following policy. Replace BUCKET_NAME with your actual S3 bucket name.

Required Permissions Summary:

• EC2 Management: Describe VPCs/Subnets/Security Groups, Create Security Groups, Run/Terminate Instances, and Create Tags.
• SSM: Fetch the latest Amazon Linux 2023 AMI ID.
• IAM: iam:PassRole to attach the chromium-build instance profile to the EC2 instance.
• S3: Full access (PutObject, GetObject, DeleteObject, ListBucket) to the specified build bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EC2BuildManagement",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:CreateSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:DescribeInstanceTypeOfferings",
        "ec2:RunInstances",
        "ec2:DescribeInstances",
        "ec2:TerminateInstances",
        "ec2:CreateTags"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SSMReadAMI",
      "Effect": "Allow",
      "Action": "ssm:GetParameters",
      "Resource": "arn:aws:ssm:*:*:parameter/aws/service/ami-amazon-linux-latest/*"
    },
    {
      "Sid": "IAMPassRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::*:role/chromium-build"
    },
    {
      "Sid": "S3ArtifactAccess",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": ["arn:aws:s3:::BUCKET_NAME", "arn:aws:s3:::BUCKET_NAME/*"]
    }
  ]
}

You can create a layer artifact locally using the provided Makefile. Replace archType with x64 or arm64 as needed.

Local Build:

archType="x64" && \
git clone --depth=1 https://github.com/sparticuz/chromium.git && \
cd chromium && \
make chromium.${archType}$.zip

Deploy to S3 and Publish via AWS CLI:

bucketName="chromiumUploadBucket" && archType="x64" && versionNumber="v135.0.0" && \
aws s3 cp chromium.${archType}.zip "s3://${bucketName}/chromiumLayers/chromium-${versionNumber}-layer.${archType}.zip" && \
aws lambda publish-layer-version --layer-name chromium --description "Chromium v${versionNumber} for ${archType}" --content "S3Bucket=${bucketName},S3Key=chromiumLayers/chromium-${versionNumber}-layer.${archType}.zip" --compatible-runtimes "nodejs20.x" "nodejs22.x" --compatible-architectures $(if [ "$archType" = "x64" ]; then echo "x86_64"; else echo "$archType"; fi)

To use @sparticuz/chromium, you must also install puppeteer-core or playwright-core. The version of @sparticuz/chromium you install must match the Chromium version supported by your chosen Puppeteer/Playwright version. Check the Puppeteer Chromium Support page to find the correct version.

Important Dependency Rules:

• puppeteer-core or playwright-core is always a production dependency.
• If you are using an AWS Lambda Layer, @sparticuz/chromium can be a dev dependency.
• If you are not using a layer, @sparticuz/chromium must be a production dependency.

If your deployment environment has strict file size limits, use the @sparticuz/chromium-min package instead, which requires you to host the Brotli files separately.

# 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