bundle-size

name	bundle-size
description	Attributes a frontend project's JavaScript bundle size to the imports that caused it, then renders a light-theme analytics website. Bundles the app with esbuild, reads the metafile, and reports how many minified KB each npm package and source module added. Use when the user runs /bundle-size or asks which import is the heaviest, what is bloating the bundle, or for a bundle-size / import-cost report.
allowed-tools	["Bash","Read","AskUserQuestion"]

Bundle Size Attribution

When invoked, you measure where a frontend bundle's bytes come from and render a light-theme website that ranks every import by the minified KB it added. The engine bundles the project with esbuild, reads esbuild's metafile, and attributes each module's bytesInOutput back to the npm package (or app file) that brought it in. The headline answer is the single import that added the most KB.

Global Context

• User request / scope: $ARGUMENTS — empty, a path to the frontend project, or an explicit entry file
• Engine: scripts/bundlesize.mjs (Node, only dependency is esbuild, installed beside the skill)
• Template: assets/template.html
• Output: bundle-size-report/index.html and bundle-size-report/data.json in the current directory

Rules

• Every number comes from esbuild's metafile. Never invent, estimate, or round-trip a size you did not measure. If the engine cannot bundle the project, say so plainly — do not fabricate a report.
• Read-only against the project. The skill only writes inside bundle-size-report/.
• Do not add comments to any command you run.
• The engine needs the project's node_modules present. If they are missing, the build cannot resolve imports.

Step 1 — Find the project

Decide the target from $ARGUMENTS:

• A path to a directory → that is the project root.
• A path to a file ending in .jsx/.tsx/.js/.ts → the project root is its package directory and that file is the entry override.
• Empty → use the current working directory as the project root.

Confirm it is a frontend project: a package.json exists and there is a src/ entry or an index.html pointing at a module script. If you cannot find one, ask the user for the entry file with AskUserQuestion rather than guessing.

Step 2 — Make sure dependencies are installed

The attributor bundles the real code, so the project's imports must resolve. Check for node_modules:

test -d <project>/node_modules && echo present || echo missing

If missing, tell the user the engine needs an install first and offer to run it:

npm --prefix <project> install

Step 3 — Run the attribution engine

Invoke the engine by its installed absolute path so it finds esbuild and the template. It always writes bundle-size-report/ into the current working directory, so run it from where you want the report. Pass the project root, and optionally an entry file:

cd <project> && node "$HOME/.claude/skills/bundle-size/scripts/bundlesize.mjs" .

With an explicit entry:

cd <project> && node "$HOME/.claude/skills/bundle-size/scripts/bundlesize.mjs" . src/main.tsx

The engine prints a short summary to stdout (heaviest import, app vs vendor split, top ten imports) and writes the full report. If esbuild fails, it explains why — most often a project that needs SCSS/LESS or path-alias resolution the bare bundler does not have. In that case, relay the error; do not produce a partial report.

Step 4 — Report back

Relay the stdout summary in your own words: name the heaviest import and the KB it added, the minified and gzipped totals, and the app-versus-vendor split. Point the user at the generated site:

bundle-size-report/index.html

Offer to open it. The page is self-contained — a treemap of imports, a ranked bar list, an app/vendor donut, a sortable table of every import, and a module-level explorer — no server or network needed.

Notes

• "Minified bytes" is each module's contribution to the minified bundle (bytesInOutput), which is the honest unit for attribution. The gzipped total is the whole bundle through zlib; per-import gzip is not reported because gzip is not additive across modules.
• npm packages are grouped by their package name (scoped packages keep their @scope/). Everything outside node_modules is grouped as (application code).
• The engine measures a production-style build: bundle, minify, format=esm, NODE_ENV=production. It is not your project's exact Vite/webpack config, but it is a faithful, repeatable attribution of the same source graph.