# BundleWatch

> BundleWatch checks the size of built browser assets in CI. It fails the build when a file is over its maxSize, compares each file with the last sizes saved for the base branch, and reports the result as a GitHub commit status with a link to a results page.

Install it with `npm install --save-dev bundlewatch`, create `bundlewatch.config.mjs` with a default-exported configuration object containing a `files` array, and run `npx bundlewatch` after the build. It searches for `bundlewatch.config.*` from the current directory up to the nearest `package.json`, checking config files before falling back to the package’s `bundlewatch` key. Use `--config` for a custom filename or location. It requires Node.js 22.17 or later. On GitHub Actions, pass the workflow's token as `BUNDLEWATCH_GITHUB_TOKEN` and grant `statuses: write`.

The whole documentation in one file: [llms-full.txt](https://bundlewatch.io/llms-full.txt)

## Introduction

- [What is BundleWatch?](https://bundlewatch.io/guide/what-is-it.md): What BundleWatch checks after each build, and how it reports the results on pull requests.
- [Getting started](https://bundlewatch.io/guide/getting-started.md): Set up BundleWatch in your project, by hand or with a coding agent.

## How to use

- [Running in CI](https://bundlewatch.io/guide/using-bundlewatch.md): Run BundleWatch on GitHub Actions or another CI provider, and read the statuses and results pages it posts.
- [Using a config file](https://bundlewatch.io/guide/using-a-config-file.md): How to configure BundleWatch using a config file or package.json.
- [Base and tracked branches](https://bundlewatch.io/guide/diffing-against-branches-other-than-master.md): How BundleWatch picks the branch to compare with, which branches save a baseline, and how files are matched with it.
- [Using a custom server](https://bundlewatch.io/guide/using-a-custom-server.md): How to run your own BundleWatch service and configure your project to use it.
- [Troubleshooting](https://bundlewatch.io/guide/troubleshooting.md): What BundleWatch's log messages mean, and what to do about them.

## Upgrading

- [Migrating to 1.0](https://bundlewatch.io/guide/migrating-to-v1.md): What changes when you upgrade from BundleWatch 0.x to 1.0.

## Reference

- [Configuration reference](https://bundlewatch.io/reference/configuration.md): Every BundleWatch option, its default, and the environment variables BundleWatch reads.
- [Command line](https://bundlewatch.io/reference/cli.md): BundleWatch's command-line options, where it reads configuration from, and its exit codes.
- [Node.js API](https://bundlewatch.io/reference/nodejs.md): Run BundleWatch from Node.js, with its result format, TypeScript types and errors.

## Optional

- [Source code and issues](https://github.com/bundlewatch/bundlewatch)
- [Compatibility contract with 0.x](https://github.com/bundlewatch/bundlewatch/blob/main/CONTRACT.md)
- [Release notes](https://github.com/bundlewatch/bundlewatch/releases)