Keep watch of your bundle size.

BundleWatch checks file sizes so bundled browser assets don't suddenly grow. A sharp increase usually means something went wrong: a package that bloats the bundle, an incorrect import, or a missing minification step.

On pull requests, it compares each file with the target branch and reports the result as a GitHub status.

Inspired by Siddharth Kshetrapal's bundlesize.

Getting started

Requires Node.js 22.17 or later.

npm install --save-dev bundlewatch

Create bundlewatch.config.mjs in your project root:

/** @type {import('bundlewatch').BundlewatchConfig} */
export default {
  files: [{ path: './dist/*.js', maxSize: '100kB' }],
}

You can also keep your configuration under the bundlewatch key in package.json. See configuration options.

Usage

Run BundleWatch after your build:

npx bundlewatch

It prints the results and exits with code 1 when a file is over its maxSize. Files are measured with gzip by default; Brotli and uncompressed sizes are also supported.

Reporting on pull requests

BundleWatch can report its status on GitHub pull requests and link to a breakdown of the changes:

GitHub Actions

Add a workflow such as .github/workflows/bundlewatch.yml:

name: bundlewatch

on:
  push:
    branches: [main] # the branches you track
  pull_request:

permissions:
  contents: read
  statuses: write

jobs:
  bundlewatch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm run build
      - run: npx bundlewatch
        env:
          BUNDLEWATCH_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The workflow's token lets BundleWatch post statuses and save baselines. Pushes to main save a baseline; pull requests are compared with the branch they target. Replace main with the branch you track, and see base and tracked branches for other branches.

Pull requests from forks get a read-only token, so BundleWatch cannot post a status on them. Size limits are still checked. See GitHub Actions setup for details.

Other CI providers

Get a token from service.bundlewatch.io/setup-github, store it as the BUNDLEWATCH_GITHUB_TOKEN secret in your CI, and run npx bundlewatch after your build.

BundleWatch detects the repository, commit and branch on supported CI providers. If a value is missing, set CI_REPO_OWNER, CI_REPO_NAME, CI_COMMIT_SHA or CI_BRANCH. When your provider cannot detect the base branch, set CI_BRANCH_BASE to the branch to compare with; otherwise comparisons use master. See supported CI providers and environment variables.

Viewing the results breakdown

Click the status's Details link, or open the results link printed in the build log, to see each file's size, limit and change from the base branch:

Multiple applications in one repository

Requires BundleWatch 1.1.0 or later, for both the CLI and Node API. Use a dependency such as "bundlewatch": "^1.1.0" and ensure CI runs that installed version. Older versions silently ignore prefix and share the unprefixed baseline and bundlewatch GitHub status. Do not downgrade a prefix-enabled application below 1.1.0.

Set prefix: 'storefront' in the storefront frontend's config and prefix: 'admin' in the admin frontend's config. Run BundleWatch from each application's directory. Their statuses become storefront/bundlewatch and admin/bundlewatch, and baselines stay independent even with identical branches and measured paths. Results pages display the prefix.

Prefixes contain 1–64 lowercase ASCII letters, digits, hyphens or underscores and start with a letter or digit. Omit prefix to keep existing names and baselines. Deploy a prefix-capable service to every instance before enabling the option in clients; unsupported services stop prefixed runs without falling back to legacy baselines. See the configuration reference and two-application example.

Node.js API

import bundlewatch, { STATUSES } from 'bundlewatch'

const results = await bundlewatch({
  files: [{ path: './dist/*.js', maxSize: '100kB' }],
})

console.log(results.summary)
if (results.status === STATUSES.FAIL) {
  process.exitCode = 1
}

CommonJS: const bundlewatch = require('bundlewatch').default. TypeScript types are included. See the Node.js API reference.

Features

• Per-file size limits with glob patterns and gzip, Brotli or no compression.
• Comparisons with the branch a pull request targets, including branches other than main or master.
• JavaScript, TypeScript and JSON configuration files, or configuration in package.json.
• A CLI and Node.js API, with TypeScript types and ES module and CommonJS builds.
• An open-source service you can host yourself.

Documentation

• bundlewatch.io: configuration, CLI and CI setup
• Configuration reference
• Migrating from 0.x
• Source and issues

Contributors

See the contributing guide to get involved.

License

MIT