Don't let your bundles go Overweight

Let’s be honest: we all care about bundle size. Or at least, we should.

For years, bundlesize was the go-to tool for this. It was the venerated guardian of our build pipelines, ensuring we didn't accidentally ship a 5MB lodash import to production. Sadly, it has become outdated and unmaintained.

I'd hoped for it to be updated, but as security checks began to scream at me for its transitive dependencies exposing all manner of issues, a replacement had to be found.
I wanted something that felt modern, required zero friction to set up, and just worked.

As one didn't simply materialize in the ecosystem, I decided I had to build one myself. Hence, Overweight 🧳⚖️.

It’s a lightweight, modern replacement for bundlesize that helps you keep your file sizes in check. It supports Gzip and Brotli compression out of the box and integrates seamlessly with your CI.

How it works

The concept is simple: you define a budget for your files. If your build artifacts exceed that budget, Overweight throws an error (and fails your build).

In the Shell
You can run it directly from the CLI to test it out. No config file needed for quick checks:

npx overweight --file "dist/*.js" --max-size 50kb

Checking with a specific tester:

npx overweight --file "dist/*.js" --max-size "15 kB" --compression brotli

Configuration
While CLI flags are great for testing, you'll want a permanent config for your project. You can add an overweight section to your package.json or create a standalone overweight[.config].json.

Here is a real-world configuration example. Notice how we can mix and match compression types and limits for different parts of the app:

{
  "checks": [
    {
      "path": "build/static/js/main.*.js",
      "maxSize": "150kb",
      "compression": "brotli"
    },
    {
      "path": "build/static/js/chunk-*.js",
      "maxSize": "50kb",
      "compression": "gzip"
    },
    {
      "path": "build/static/css/*.css",
      "maxSize": "20kb",
      "compression": "none"
    }
  ]
}

Now, you just run:

npx overweight 

or if you installed locally:

pnpm overweight

And you get a detailed report

GitHub Workflow Integration

This is where Overweight really shines. You don't want to manually run this; you want it blocking PRs that bloat your app.

Below is a drop-in GitHub Action workflow. It runs on pull requests, builds your project, and then lets Overweight do the policing.

name: bundle-overweight-test

on:
  pull_request:
  push:
    branches: [main]

jobs:
  overweight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4     
      - uses: yoavniran/overweight@v1
        with:
          config: overweight.json          
          update-baseline: true
          report-file: overweight-report.json
          github-token: ${{ secrets.GITHUB_TOKEN }}

In case there is a file being tested that exceeds its allowed max size, Overweight will fail the flow.

When update-baseline is true and there are changes to the report (due to file size or config changes), the action will create a separate PR to update the report file.

To Summarize

Overweight gives you:

• Modern Defaults: Built for today's CI environments.
• Flexible Config: Glob patterns, per-file compression settings (Brotli/Gzip/None).
• Zero Config CLI: easy to try out without committing to a config file.
• Reliable CI: It just works with GitHub Actions.

Give it a try and stop worrying about your bundle size creeping up on you.

Check out Overweight on GitHub

If you like it, give it a ⭐️