bundlemon

Monitor your bundle size

weekly downloads44K

versionv3.1.0

licenseMIT

categorytoolchain

bundlesizebundlesizemonitor

Overview

bundlemon is an open-source bundle monitoring tool that tracks your application's bundle size across commits and pull requests. It integrates directly into your CI/CD pipeline to provide automatic checks, comparisons against your base branch, and historical tracking of how your bundle size evolves over time.

The package addresses a common problem in modern JavaScript development: bundle size often increases gradually without teams noticing until performance degrades. By making bundle size visible on every commit and PR, bundlemon creates accountability and helps teams make informed decisions about dependencies and code changes. With over 44,000 weekly downloads, it's become a standard tool for teams serious about frontend performance.

bundlemon works by analyzing your build output after compilation, comparing file sizes against previous commits, and reporting changes in formats your team actually sees—PR comments, CI status checks, and web dashboards. It handles real-world scenarios like webpack's dynamic hash filenames and supports multiple compression formats (gzip, brotli) to match your production environment. The tool can be configured to fail CI builds when bundles exceed specified thresholds, preventing performance regressions from reaching production.

Quick Start

typescript

// .bundlemonrc.json
{
  "baseDir": "./build",
  "files": [
    {
      "path": "static/js/main.<hash>.js",
      "maxSize": "200kb",
      "maxPercentIncrease": 10
    },
    {
      "path": "static/js/vendor.<hash>.js",
      "maxSize": "500kb"
    },
    {
      "path": "static/css/**/*.css",
      "maxSize": "50kb"
    }
  ],
  "defaultCompression": "gzip",
  "reportOutput": ["github", "json"]
}

// GitHub Actions workflow (.github/workflows/bundlemon.yml)
// name: Monitor Bundle Size
// on: [push, pull_request]
// jobs:
//   bundlemon:
//     runs-on: ubuntu-latest
//     steps:
//       - uses: actions/checkout@v3
//       - uses: actions/setup-node@v3
//       - run: npm ci
//       - run: npm run build
//       - run: npx bundlemon
//         env:
//           BUNDLEMON_PROJECT_ID: ${{ secrets.BUNDLEMON_PROJECT_ID }}
//           CI_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}

Use Cases

Preventing bundle bloat in feature branches: Set up bundlemon to comment on every PR with size comparisons, making developers aware when their changes significantly increase bundle size before merge. This creates a review checkpoint where teams can evaluate whether the size increase is justified.

Enforcing bundle budgets per file: Configure maximum size limits for specific chunks like vendor bundles or main application code. When a change exceeds these limits, the CI check fails, requiring developers to optimize or justify the increase before proceeding.

Tracking performance over time: Use bundlemon's historical charts to identify trends in bundle growth across releases. This helps teams spot gradual increases that might not trigger alarms on individual PRs but represent significant bloat over months.

Monitoring third-party dependency impact: When evaluating new libraries, bundlemon quantifies exactly how much size each dependency adds. Teams can make data-driven decisions about whether a convenience library is worth the performance cost.

Multi-environment optimization: Configure different compression settings (gzip vs brotli) to match your CDN configuration, ensuring your monitoring reflects real user experience rather than uncompressed development builds.

Pros & Cons

Pros

+Integrates seamlessly with GitHub Actions, GitLab CI, and other CI/CD platforms with minimal configuration
+Supports dynamic webpack hash filenames out of the box using placeholder patterns
+Free and open-source with no service dependencies required for basic usage (self-hosted mode available)
+Provides actionable PR comments showing per-file changes, not just aggregate totals
+Configurable thresholds per file allow granular control over what constitutes acceptable growth

Cons

−Requires additional setup and API tokens to access advanced features like historical charts via BundleMon service
−Documentation focuses heavily on GitHub Actions; other CI platforms require more manual configuration
−No built-in support for analyzing why bundles increased—only reports that they did, requiring separate tools for deep analysis
−Configuration file syntax can become verbose for projects with many chunks and complex path patterns
−Relies on consistent build output paths; changes to your build configuration may require updating bundlemon config

Alternatives

size-limitv12.0.0

CLI tool for Size Limit

toolchainsize-limitcli

542K / week

Comparisons

size-limit vs bundlemon

toolchain

Install

bash

npm install bundlemon

bash

pnpm add bundlemon

bash

bun add bundlemon

Overview

Quick Start

typescript

// .bundlemonrc.json
{
  "baseDir": "./build",
  "files": [
    {
      "path": "static/js/main.<hash>.js",
      "maxSize": "200kb",
      "maxPercentIncrease": 10
    },
    {
      "path": "static/js/vendor.<hash>.js",
      "maxSize": "500kb"
    },
    {
      "path": "static/css/**/*.css",
      "maxSize": "50kb"
    }
  ],
  "defaultCompression": "gzip",
  "reportOutput": ["github", "json"]
}

// GitHub Actions workflow (.github/workflows/bundlemon.yml)
// name: Monitor Bundle Size
// on: [push, pull_request]
// jobs:
//   bundlemon:
//     runs-on: ubuntu-latest
//     steps:
//       - uses: actions/checkout@v3
//       - uses: actions/setup-node@v3
//       - run: npm ci
//       - run: npm run build
//       - run: npx bundlemon
//         env:
//           BUNDLEMON_PROJECT_ID: ${{ secrets.BUNDLEMON_PROJECT_ID }}
//           CI_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.sha }}

Use Cases

Pros & Cons

Pros

+Integrates seamlessly with GitHub Actions, GitLab CI, and other CI/CD platforms with minimal configuration
+Supports dynamic webpack hash filenames out of the box using placeholder patterns
+Free and open-source with no service dependencies required for basic usage (self-hosted mode available)
+Provides actionable PR comments showing per-file changes, not just aggregate totals
+Configurable thresholds per file allow granular control over what constitutes acceptable growth

Cons

−Requires additional setup and API tokens to access advanced features like historical charts via BundleMon service
−Documentation focuses heavily on GitHub Actions; other CI platforms require more manual configuration
−No built-in support for analyzing why bundles increased—only reports that they did, requiring separate tools for deep analysis
−Configuration file syntax can become verbose for projects with many chunks and complex path patterns
−Relies on consistent build output paths; changes to your build configuration may require updating bundlemon config