simple-bundle-diff-reporter

Simple, zero-dependency bundle size diff-reporter that compares your current build against a baseline (e.g., master/main) and generates a rich Markdown report. It flags files that changed significantly, were added/removed, and highlights bundles that are too large or too small to split.

Why use this?

• Fast, simple, and framework-agnostic: Works with any JS build output folder.
• Actionable report: Clear summary + drill-down sections in Markdown.
• Enforce size budgets: Fail CI when bundles exceed limits or are undersized.
• Hash-safe comparison: Normalizes hashed filenames so diffs remain meaningful.

Installation

npm i -D simple-bundle-diff-reporter
# or
yarn add -D simple-bundle-diff-reporter
# or
pnpm add -D simple-bundle-diff-reporter

Quick start

1. Build your project so your bundles exist (defaults to dist/).

2. On your baseline branch (e.g., main), generate and store the baseline stats:

const BundleReporter = require('simple-bundle-diff-reporter');

const reporter = new BundleReporter({
  buildFolder: 'dist',
  outputFolder: 'bundle-diff-reporter',
  masterFile: 'master-bundle-stats.json',
  currentFile: 'current-bundle-stats.json'
});

reporter.generateBundleStats();
// rename the output bundle-diff-reporter/current-bundle-stats.json to master-bundle-stats.json

Commit the generated bundle-diff-reporter/master-bundle-stats.json to your repo (or store as an artifact accessible in CI).

3. On your feature/PR branch, after building, generate the current stats and the comparison report:

const BundleReporter = require('simple-bundle-diff-reporter');

const reporter = new BundleReporter({
  buildFolder: 'dist',
  outputFolder: 'bundle-diff-reporter',
  masterFile: 'master-bundle-stats.json',
  currentFile: 'current-bundle-stats.json'
});


// Writes bundle-diff-reporter/current-bundle-stats.json
reporter.generateBundleStats();

// Writes bundle-diff-reporter/bundle-size-report.md 
reporter.generateReport();

Options

Option	Type	Default	Description
buildFolder	string	"dist"	Folder containing your built JS files.
outputFolder	string	"bundle-diff-reporter"	Where to write all outputs.
changeThreshold	number	5	Minimum % size change to count a file as "changed" in the report.
splittingUpperLimit	number (KB)	250	Files larger than this are flagged as above average.
splittingLowerLimit	number (KB)	20	Split chunks smaller than this are flagged as below average.
masterFile	string	"master-bundle-stats.json"	Baseline stats filename inside outputFolder.
currentFile	string	"current-bundle-stats.json"	Current stats filename inside outputFolder.
outputFile	string	"bundle-size-report.md"	Markdown report filename inside outputFolder.
failureFile	string	"bundle-diff-stage-failed.txt"	Created when the check fails.
aboveAverageFiles	string[]	[]	Allowlist: filenames that may exceed splittingUpperLimit without failing.
belowAverageFiles	string[]	[]	Allowlist: filenames that may be below splittingLowerLimit without failing.

Notes:

• Filenames are normalized (e.g., hashed suffixes/chunk markers are removed) to make comparisons stable between builds.
• Files containing "resolver" in the name are ignored for the below-average check by default.

Outputs

All outputs go to outputFolder (default bundle-diff-reporter/):

• master-bundle-stats.json — Baseline bundle map { [fileName]: { size: number(KB) } }.
• current-bundle-stats.json — Current bundle map, same shape, sorted by size.
• bundle-size-report.md — Human-friendly Markdown report with collapsible sections.
• bundle-diff-stage-failed.txt — Only written when the check fails.

Report preview

Below is an example of the generated report. It contains:

• Header + pass/fail message
• Summary table
• Changed Files (with threshold note and size budget reminder)
• Above Average Files (exceed splittingUpperLimit)
• Below Average Files (below splittingLowerLimit)
• New Files
• Removed Files

Success example

Failure example

Suggested CI usage (example)

Run after your build step. If the diff-reporter writes the failure flag file, fail the job:

 stage('generate-bundle-reports') {       
            // build the app to generate dist
            sh '''#!/usr/bin/env bash
              set -x
              export NODE_OPTIONS="--max-old-space-size=4096"
              yarn build
            '''

            // Download with retries
            retry(3) {
                s3Download(
                  bucket: 's3-bucket-name',
                  path: "s3-bucket-name/master-bundle-stats.json",
                  file: 'bundle-diff-reporter/master-bundle-stats.json',
                )
              }
            // Verify download
            if (!fileExists('bundle-diff-reporter/master-bundle-stats.json')) {
              error("Master bundle stats file missing after download")
            }
            else {
                sh '''#!/usr/bin/env bash
                  set -x
                  export NODE_OPTIONS="--max-old-space-size=4096"
                  node bundle-diff-reporter/index.js
                '''
                def report = readFile file: 'bundle-diff-reporter/bundle-size-report.md'
                pullRequest.comment("${report}") // to comment the output of bundle-diff-reporter as PR comment
                if (fileExists('bundle-diff-reporter/bundle-diff-stage-failed.txt')) {
                  error("🔴 Failed to pass bundle size check")
                }
              }
          }

FAQs

• Do I need to commit the baseline file? You can commit bundle-diff-reporter/master-bundle-stats.json or fetch/store it via CI artifacts. The diff-reporter needs access to it when running comparisons.

• What files are analyzed? .js files in buildFolder. Filenames are normalized by removing common hash/chunk patterns.

• Can I ignore specific files for size budgets? Yes. Use aboveAverageFiles and belowAverageFiles to allowlist exceptions.

License

MIT