Bundle Budget Plugin

[BioPhoton]

📦 Bundle Budget Plugin

Bundle size tracking for your build artifacts
Track, compare, and prevent bundle size regressions to maintain web performance (e.g. LCP) across product areas.

---

🧪 Reference PR

👉 #PoC – BundleBudget Plugin PoC Implementation

---

User story

As a developer, I want to track bundle size regressions per product area and route,
so that we can avoid performance regressions and optimize LCP over time.

The plugin should:

• Analyze stats.json output from different bundler.
• Identify and compare main, initial, and lazy chunks over glob matching
• Use chunk input fingerprinting to map renamed chunk files.
• Group chunk sizes by route/product (e.g., /route-1, /route-2).
• Store and compare bundle stats across versions/releases.

Metric

Bundle size in bytes.
Parsed from --stats-json output and grouped by file.

Property	Value	Description
value	132341	Total size of all chunks.
displayValue	13.4 MB / 13 Files	Display value inc. number of files.

Integration Requirements

The plugin can be implemented in 2 ways:

1. Using stats files
2. Crawling the filesystem

As stats file serve significantly more details and are state of the art when debugging bundle size this issue favours this approach.

Using Stats Files

Bundle stats are detailed metadata about your build outputs—listing each generated file, its original inputs, and any static imports—exported via a metafile (e.g. from ESBuild or other bundlers).

Generate a stats file with ESBuild:

esbuild src/index.js --bundle  --outfile=dist/bundle.js  --metafile=stats.json

The resulting file maintains the following data structure:

EsbuildBundleStats
├── inputs (Record<string, MetafileInput>)
│   └── <inputPath>
│       ├── bytes: number
│       └── imports (MetafileImport[])
│           └── [ ]
│               ├── path: string
│               ├── kind: ImportKind
│               ├── external?: boolean
│               └── original?: string
└── outputs (Record<string, MetafileOutput>)
    └── <outputPath>
        ├── bytes: number
        ├── inputs (Record<string, MetafileOutputInput>)
        │   └── <inputPath>
        │       └── bytesInOutput: number
        ├── imports (MetafileImport[])
        │   └── [ ]
        │       ├── path: string
        │       ├── kind: ImportKind
        │       ├── external?: boolean
        │       └── original?: string
        ├── exports: string[]
        └── entryPoint?: string

The plugin will use this information to gather the configured artefact groups.

Crawling the filesystem

Note

No research done as not scaleable

Setup and Requirements

📦 Package Dependencies

• Dev Dependencies:
  • None required, optional CLI runner for local debugging.
• Optional Dependencies:
  • esbuild – or any tool that emits --metafile/stats.json.

📝 Configuration Files

• angular.json / vite.config.ts or equivalent – for custom build config.
• No required config file for the plugin itself.

---

Implementation details

Data Processing Pipeline

flowchart LR
  subgraph Stats Generation
    A[Esbuild ➔ stats.json] 
    B[Webpack ➔ stats.json]
    C[Vite ➔ stats.json]
  end

  D[Unify Stats]
  E[Apply Plugin Config]
  F[Compute Size Scores]
  G[Compute Issue Penalties]
  H[Blend into Final Score]
  I[Generate Audits & Tree Display & Issues]

  A --> D
  B --> D
  C --> D
  D --> E
  E --> F
  E --> G
  F --> H
  G --> H
  H --> I

Loading

Plugin Types

export type SupportedBundlers = 'esbuild' | 'webpack' | 'vite' | 'rsbuild';

export type MinMax = [number, number];

export interface BundleStatsConfig {
  name: string;
  include?: string[];
  exclude?: string[];
  thresholds: {
    totalSize: number | MinMax;
    artefactSize?: number | MinMax;
  };
  // includeInputs?: string[]; 
}

export interface GroupingOptions {
  name: string;
  patterns: PatternList;
  icon?: string;
  depth?: number;
}

export interface PruningOptions {
  maxChildren?: number;
  startDepth?: number;
  maxDepth?: number;
}

export type PluginOptions {
  generateArtefacts?: string;
  artefactsPath: string;
  bundler: SupportedBundlers;
  customAudits: BundleStatsConfig[];
  tree: boolean | {
    grouping?: GroupingOptions;
    pruning?: PruningOptions;
  }
}

Plugin Usage

const config = {
plugins: [
  bundleStatsPlugin({
    generateArtefacts: "nx run app-1:build --stats",
    artefactsPath: "./stats.json",
    bundler: 'esbuild',
    configs: [
     { 
         name: "Initial Bundles",
         include: ["main.js", "vendor.js"],
         thresholds : { totalSize: 5000 }
      },
      {
          name: 'Lazy Products',
          include: ['src/app/products/**', '!src/app/products/shared/**'],
          thresholds: {
             totalSize: 1000,
             artefactSize: 100
          }
        }
     ]
  })
]
}

Audits

A audit encapsulates a group of artefacts determined by BundleStatsConfig.

Scoring

The plugin assigns a score in the range [0 … 1] to each artefact (or artefact group) based on its byte size relative to a configurable maximum threshold (maxArtefactSize). A perfect score (1) means “within budget,” and a zero score (0) means “critically over budget.”

Scoring Parameters

Parameter	Description
S	Actual bytes
M	Size threshold bytes
E	Number of “Too Large” (🚨) errors
W	Number of “Too Small” (⚠️) warnings
we	Weight per error (default 1)
ww	Weight per warning (default 0.5)

Size score

$\mathrm{sizeScore} = \begin{cases} 1, & S \le M\\[6pt] \max\bigl(0,\;1 - \tfrac{S - M}{M}\bigr), & S > M \end{cases}$

Issues penalty

$penalty = we * E + ww * W$

Final blended score

$\mathrm{finalScore} = \max\!\Bigl(0,\;\mathrm{sizeScore} - \frac{\mathrm{penalty}}{we + ww}\Bigr)$

xychart-beta
 title "Score vs Artifact Size (with penalty shift)"
    x-axis [0, 1, 1.25, 1.5, 1.75, 2]
    y-axis "Score" 0 --> 1
    line Original [1, 1, 0.75, 0.5, 0.25, 0]
    line Penalized [0.5, 0.5, 0.25, 0, 0, 0]

Loading

Issues

The plugin optionally creates diagnostic for the given artefacts.
The following table shows all different options:

Diagnostic	Description	Config Key	Default	Severity	Recommended Action
Too Large 🚨	Artifact exceeds the maximum allowed size. May indicate an unoptimized bundle or accidentally checked-in	binary.	maxArtifactSize	5 MB	Error
Too Small ⚠️	Artifact is below the minimum expected size. Could signal missing dependencies or incomplete build.	minArtifactSize	1 KB	Warn	Verify that the build output is complete and dependencies are included.

Example Issues:

Severity	Message	Source file	Line(s)
🚨 error	main.js is 6.12 MB (max 5 MB); enable code-splitting or lazy-loading.	dist/lib/main.js
🚨 error	vendor.js is 2.05 MB (max 1.5 MB); apply tree-shaking or serve libs via CDN.	dist/lib/vendor.js
⚠️ warning	utils.js is 50 kB (min 100 kB); verify bundling.	dist/lib/utils.js
⚠️ warning	styles.css is 10 B (min 1 kB); check CSS inclusion.	dist/lib/styles.css

Artefact Tree

Example:

🗂️ example-group                         237.17 kB   101 files
├── 📍 entry-1.js                         138 kB    2 files
│   ├── 📄 src/input-1.ts                 101 kB        
│   └── 📄 src/input-2.ts                  37 kB      
├── 📄 entry-2.js                             30 kB 2 files   
│   ├── 📄 node_modules/@angular/router/provider.js            
│   └── 📄 node_modules/@angular/router/service.js            
├── 🎨 styles.css                             14 kB        
└── 🔗 static imports from 📍 entry-1.js     104 kB    
    └── 📄 file-1.js   

Artefact Types

Each group is also displayed as tree of artefacts, inputs and static imports.
The following types are detected.

• 📄 - script file - JS/TS artefact
• 🎨 - style files - CSS/SCSS artefacts
• 📍 - entry file - JS/TS artefact
• 🔗 - static imports - List of S/TS artefacts statically imported by another file

🗂️ example-group                             190 kB  4 files
├── 📍 entry-1.js                            100 kB   2 files
├── 📄 file-1.js                                 30 kB   2 files   
├── 🎨 styles.css                             10 kB        
└── 🔗 static imports from 📍 entry-1.js  
    └── 📄 file-2.js                            50 kB

Artefact Inputs

Each artefact is maintains out of inputs ind imports. The inputs are listed under each chunk.

🗂️ example-group                              60 kB  1 files
└── 📄 file-1.js                                60 kB  3 files   
    ├── 📄 src/lib/cli.js
    │    └── 📄 node_modules/yargs/yargs.js       
    └── 📄 node_modules/zod/helpers       
        └── 📄 node_modules/zod/helpers/description.js       

Artefact Imports

Each artefact imports that are statically imported and directly contribute to the artefact group size are listed under dedicated import groups per file. This is helpful to understand the true size of you artefact group.
Static imports are loaded together with it's importing parent and therefore will end up in the loaded bytes. Displaying them helps to inderstand why they are part and where they aer imported from.

🗂️ example-group                                           150 kB  6 files
├── 📍 entry-1.js                                          100 kB  
├── 📄 file-1.js                                               50 kB  
├── 🔗 static imports from 📍 entry-1.js     60 kB  2 files     
│    ├── 📄 file-2.js                                         40 kB   
│    └── 📄 file-3.js                                        40 kB   
└── 🔗 static imports from 📄 file-1.js        80 kB  2 files    
    ├── 📄 file-4.js                                          40 kB    
    └── 📄 file-5.js                                         40 kB     

Artefact Grouping

Artefact inputs can be grouped over the configuration.

Ungrouped:

🗂️ example-group                             150 kB  1 files
└── 📄 entry-2.js                            150 kB  3 files   
    ├── 📄 node_modules/@angular/router/provider.js            
    └── 📄 node_modules/@angular/router/service.js       
        └── 📄 node_modules/@angular/router/utils.js       

Grouped by:

• patterns - node_modules/@angular/router
• name - @angular/router
• icon - "🅰️"
• depth - 1

🗂️ example-group                             150 kB  1 files
└── 📄 entry-2.js                           150 kB  1 files
    └─  🅰️ @angular/router           

Tree Pruning

The artefact tree can get quite dense in information. To avoid overload we reduce the amount of visible nodes.

Unpruned:

🗂️ example-group                           800 kB   10 files
├── 📍 index.js                             250 kB    4 files
│   ├── 📄 src/app.js                       120 kB    3 files
│   │   ├── 📄 src/components/Header.js      40 kB    2 files
│   │   │   ├── 📄 src/components/Logo.js     15 kB    1 file
│   │   │   └── 📄 src/components/Nav.js      25 kB    1 file
│   │   └── 📄 src/utils/math.js             30 kB    1 file
│   ├── 📄 src/route-1.js                     120 kB    3 files
│   ├── 📄 src/route-2.js                     120 kB    3 files
│   └── 📄 src/main.css                       50 kB    1 file
├── 📄 vendor.js                             300 kB    5 files
│   ├── 📄 node_modules/react.js             100 kB    1 file
│   ├── 📄 node_modules/react-dom.js          80 kB    1 file
│   ├── 📄 node_modules/redux.js              60 kB    1 file
│   ├── 📄 node_modules/react-router.js       40 kB    1 file
│   └── 📄 node_modules/lodash.js             20 kB    1 file
└── 📄 logo.svg                              250 kB    1 file

Pruning options:

• startDepth - 1
• maxChildren - 1
• maxDepth - 3

Pruned:

🗂️ example-group                             150 kB  10 files
├── 📍 index.js                             250 kB    4 files
│   ├── 📄 src/app.js                       120 kB    
│   └── … 3 more inputs                    130 kB    
├── 📄 vendor.js                             300 kB    5 files
│   ├── 📄 node_modules/react.js             100 kB    
│   └── … 4 more inputs                            200 kB    
└── 📄 logo.svg                              250 kB    

Report examples

---

Code PushUp Report

🏷 Category	⭐ Score	🛡 Audits
Bundle Size	🟡 54	13

🏷 Categories

Performance

Bundle size metrics 📖 Docs

🟢 Score: 92

• 🟥 Bundle size changes InitialChunk (BundleSize) - 1 warning
• 🟡 Bundle size changes InitialChunk (BundleSize)

🛡️ Audits

Bundle size changes InitialChunks (CodePushUp)

🟥 3 info (score: 0)

Initial Chunks

🗂️ initial-bundles                               237.16 kB  101 files
├── 📍 main-XTHQ3HCO.js                            98.01 kB   14 files
│   ├── src/app/app.routes.ts                         101 B     1 file
│   ├── src/app/app.config.ts                          53 B     1 file
│   ├── src/app/app.component.ts                   17.59 kB     1 file
│   ├── src/main.ts                                    37 B     1 file
│   ├── 🅰️ @angular/common                         5.46 kB    4 files
│   ├── 🅰️ @angular/platform-browser              11.47 kB    3 files
│   └── 🅰️ @angular/router                        63.31 kB    3 files
├── 📍 polyfills-B6TNHZQ6.js                       33.77 kB    2 files
│   ├── angular:polyfills:angular:polyfills                     1 file
│   └── 📦 zone.js                                 33.77 kB     1 file
├── 📄 styles-EGIV7BA7.css                            631 B     1 file
└── 🔗 static imports from 📍 main-XTHQ3HCO.js    104.76 kB   84 files
    └── 📄 chunk-5QRGP6BJ.js

Issues

Severity	Message	Source file	Line(s)
⚠️ warning	Bundle size (236.51 kB) is below minimum threshold (300 kB)

---

CI Comment

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Bundle size	Total	🟨 12.0 MB	🟥 13.1 MB	↑ +9.2 %
Bundle size	Initial Chunks	🟩 6.0 MB	🟩 6.2 MB	↑ +3.3 %
Bundle size	Lazy Chunks	🟥 6.0 MB	🟥 6.9 MB	↑ +15.0 %
Bundle size	Main Bundle	🟨 5.0 MB	🟥 5.2 MB	↑ +4.0 %
Bundle size	Auth Module	🟨 1.1 MB	🟥 1.3 MB	↑ +18.2 %
Bundle size	Lazy Products	🟩 3.0 MB	🟩 3.1 MB	↑ +3.3 %

---

Market Research

SizeLimit

Repo: https://github.com/ai/size-limit

Setup

import type { SizeLimitConfig } from '../../packages/size-limit'

module.exports = [
  {
    path: "index.js",
    import: "{ createStore }",
    limit: "500 ms"
  }
] satisfies SizeLimitConfig

Relevant Options:

• path: relative paths to files. The only mandatory option.
  It could be a path "index.js", a [pattern] "dist/app-*.js"
  or an array ["index.js", "dist/app-*.js", "!dist/app-exclude.js"].
• import: partial import to test tree-shaking. It could be "{ lib }"
  to test import { lib } from 'lib', * to test all exports,
  or { "a.js": "{ a }", "b.js": "{ b }" } to test multiple files.
• limit: size or time limit for files from the path option. It should be
  a string with a number and unit, separated by a space.
  Format: 100 B, 10 kB, 500 ms, 1 s.
• name: the name of the current section. It will only be useful
  if you have multiple sections.
• message: an optional custom message to display additional information,
  such as guidance for resolving errors, relevant links, or instructions
  for next steps when a limit is exceeded.

• gzip: with true it will use Gzip compression and disable
  Brotli compression.
• brotli: with false it will disable any compression.
• ignore: an array of files and dependencies to exclude from
  the project size calculation.

Bundle Stats

repo: https://github.com/relative-ci/bundle-stats?tab=readme-ov-file

Setup

const { BundleStatsWebpackPlugin } = require('bundle-stats-webpack-plugin');

module.exports = {
  plugins: [
    new BundleStatsWebpackPlugin({
      compare: true,
      baseline: true,
      html: true
    })
  ]
};

Relevant Options

• compare | Enable comparison to baseline bundle
• baseline | Save stats as baseline for future runs
• html | Output visual HTML report
• json | Output JSON snapshot
• stats | (advanced) Customize Webpack stats passed into plugin
• silent | Disable logging

---

BundleMon

Repo: https://github.com/LironEr/bundlemon

Setup

"bundlemon": {
  "baseDir": "./build",
  "files": [
    {
      "path": "index.html",
      "maxSize": "2kb",
      "maxPercentIncrease": 5
    },
    {
      "path": "bundle.<hash>.js",
      "maxSize": "10kb"
    },
    {
      "path": "assets/**/*.{png,svg}"
    }
  ]
}

Relevant Options

• path (string, required) – Glob pattern relative to baseDir (e.g. "**/*.js")
• friendlyName (string, optional) – Human-readable name (e.g. "Main Bundle")
• compression ("none" | "gzip", optional) – Override default compression (e.g. "gzip")
• maxSize (string, optional) – Max size: "2000b", "20kb", "1mb"
• maxPercentIncrease (number, optional) – Max % increase: 0.5 = 0.5%, 4 = 4%, 200 = 200%

[Karnaukhov-kh]

Severity	Message	Source file	Penalty
🚨 error	Chunk too big – 198.7 KB (allowed 3 - 14 KB)	main-TVMA6NI7.js	-1
⚠️ warning	Size increase +5 % (allowed 3 – 14 %)	chunk-5QRGP6BJ.js	-0.5
ℹ️ info	Chunk size 9 KB (allowed 3 – 14 KB)	polyfills.js	0
🚨 error	Chunk too small – 0.34 KB (allowed 3 – 14 KB)	chunk-NY7Q4ZJ6.js	-1

Penalty system is what I miss in the current table, I can see issues and... What should I do with them? Why should I care? How they affect the 92 score?

Most of the things should be binary and have error or info states. Error can hapen with violation of both - high and low limits.
Only exception is % increase that could have warning if in between the ranges. If it's above the range should be error, below - info.

Consumer should be able to configure % change to negative numbers also, so if we track improvement we (users) can say improvement was not enough. For example we have a goal to cut 5% of main bundle size with each release, then range should be -5 - 0.

Simplistic -1, -0.5 have downsides because having 15KB and 198KB treated as the same level of violation, so this needs refinement.

[beaussan]

Hello! Super eager for this to land!

How would the vite support look like?

Maybe you can use a bundler agnostic analysis tool (as json output) to have something universal? https://sonda.dev/