How to Track Bundle Size with GitHub PR Bots

Automated GitHub pull request bots allow web development teams to detect, monitor, and prevent bundle size bloat before code reaches production. By calculating asset sizes on every commit, comparing them against the base branch, and posting detailed diff summaries directly into pull request discussions, these tools keep application performance top-of-mind. This article explains how these bots function within modern continuous integration (CI) pipelines, the primary tools available, and best practices for enforcing performance budgets across engineering teams.

The Mechanics of PR-Based Bundle Tracking

Bundle tracking bots integrate directly into CI/CD workflows via platforms like GitHub Actions. When a developer opens a pull request, the automated process follows a standard sequence:

  1. Build and Measure the PR Branch: The CI runner compiles the project, runs minification and compression (such as Gzip or Brotli), and records the final byte sizes of generated JavaScript, CSS, and asset chunks.
  2. Retrieve Baseline Metrics: The runner pulls the corresponding build metrics from the target branch (typically main or production), either by checking out and building that commit or by retrieving cached build artifacts from cloud storage.
  3. Calculate the Delta: The tool computes the difference in file sizes across individual chunks and total assets.
  4. Report via PR Comment: A GitHub bot comments directly on the pull request with a Markdown table detailing added, modified, or removed chunks alongside percentage changes.

Common Tools and Integrations

Engineering teams rely on several open-source actions and specialized platforms to handle measurement and reporting:

  • Size Limit: A performance-budget tool for JavaScript that calculates execution time as well as file size. It features an official GitHub Action that posts visual size diffs to PRs.
  • Compressed Size Action: A popular GitHub Action that reports changes in Gzip- and Brotli-compressed assets without requiring external servers.
  • Bundlewatch: A standalone service and CLI tool that integrates with CI to validate file sizes against predefined limits, setting commit statuses directly in GitHub.
  • Bundlesize: A lightweight utility designed to fail CI pipelines when assets exceed specified thresholds.

Enforcing Performance Budgets and Blocking Regressions

Automating visibility is often not enough to prevent bloat; teams also configure these tools to enforce hard or soft performance budgets:

  • Status Checks (Passing/Failing): Bots can register as required GitHub status checks. If a change introduces an unexpectedly large dependency that exceeds a predefined threshold (e.g., a single package adding more than 15 KB), the bot sets the status check to failed, preventing the pull request from merging.
  • Warning Thresholds: Teams often set non-blocking warning thresholds. For instance, a 5% increase might trigger an automated warning label or a notification pinging the core frontend team for review.

Best Practices for Implementation

To make bundle tracking effective without slowing down development velocity, teams should follow specific implementation practices:

  • Track Compressed Sizes: Always measure Gzip or Brotli sizes rather than raw disk size, as compressed bytes reflect what users actually download over the network.
  • Cache Baseline Builds: Rebuilding the main branch on every PR significantly increases CI run times and costs. Store build stats as CI artifacts or in remote object storage (like AWS S3) during main-branch deployments to enable instant comparisons.
  • Break Down by Route or Chunk: Tracking only the total bundle size obscures regressions. Configure bots to display changes per route, entry point, and dynamic import so developers can immediately identify which part of the code expanded.
  • Pair with Bundle Analyzers: When a bot flags a size increase, developers need immediate actionable insights. Provide an automated link to generated visual analyzer reports (such as Webpack Bundle Analyzer or Vite Rollup Plugin Visualizer) so engineers can identify the exact third-party package or duplicated code causing the bloat.