bundle-size-usage

bundle-size-usage helps you understand which source files contribute the most bytes to an esbuild bundle. It parses the inline path comments that esbuild appends to each wrapped module and returns a size summary that you can consume through a CLI or programmatically.

Features

• Parses esbuild IIFE bundles and reports per-file byte usage
• CLI sorts output from largest to smallest so hotspots stand out immediately
• CLI hides tree-shaken (disabled) modules so you only see shipped code
• Ships with both a CLI and a tiny TypeScript-first API
• Zero runtime dependencies and works in Node.js or the browser

Installation

You can also install bundle-size-usage with pnpm, yarn, or slnpm.

CLI Usage

• Pass one or more bundle files; the CLI prints a separate section for each.
• Use --help to see usage information or --version to print the current package version.
• The command exits with a non-zero status if no recognizable esbuild modules are found.

Library Usage

You can embed bundle-size-usage into your own tooling to analyze bundle contents, build dashboards, or fail CI when modules cross a threshold.

• parseFile reads the bundle from disk and returns an array of { path, size }.
• Returned items keep the original bundle order; sort manually (as above) if you want a different view.
• Filter out entries whose path begins with (disabled): if you want parity with the CLI output.
• Use parseCode when you already have the bundle contents loaded as a string.
• The function ignores sections that esbuild marks as (disabled) so your numbers reflect what actually ships.

TypeScript Signatures

How It Works

esbuild adds comment headers such as // src/components/App.tsx before each wrapped module. bundle-size-usage reads those sections, measures the byte length of the module body, and sums it per file. Disabled chunks (e.g. tree-shaken modules) are skipped so you only see the code that lands in the output bundle.

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others