Don't let your bundles go Overweight

Source: Dev.to

What is Overweight?

Overweight is a modern, zero‑config CLI that lets you define size budgets for your build artifacts. If any file exceeds its budget, Overweight throws an error, causing your CI pipeline to fail.

Installation & Usage

You can run Overweight directly with npx:

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

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

If you prefer a local installation:

pnpm add -D overweight
pnpm overweight

Configuration

Add an overweight section to your package.json or create a standalone overweight.config.json file. Below is a real‑world example that mixes compression types and limits for different parts of an 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"
    }
  ]
}

Run the check with the configured budgets:

npx overweight

CI Integration

Overweight shines when used in CI to block pull requests that bloat your app. Below is a drop‑in GitHub Action workflow that runs on PRs and pushes to main:

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 }}

• If a file exceeds its allowed size, the job fails.
• When update-baseline is true and the report changes (due to size or config updates), the action creates a separate PR to update the report file.

Features

• Modern defaults – built for today’s CI environments.
• Flexible config – glob patterns, per‑file compression settings (Brotli, Gzip, or none).
• Zero‑config CLI – try it out without committing a config file.
• Reliable CI – works seamlessly with GitHub Actions.

Get Started

Give Overweight a try and stop worrying about bundle size creep.

Check out Overweight on GitHub – if you like it, consider giving it a ⭐️.