What is an esbuild metafile?

A JSON file esbuild writes with `--metafile=meta.json`, describing every input, every output and which modules ended up in which chunk. It is the data behind any bundle treemap for an esbuild build.

How do I turn it into a page?

`npx esbuild-visualizer --metadata meta.json --filename stats.html` renders a standalone treemap. esbuild's own online Bundle Size Analyzer takes the same file if you only need a one-off look.

Does this work for Vite or tsup?

Both use esbuild or Rollup underneath. tsup can pass `--metafile`; for Vite's production build, `rollup-plugin-visualizer` is the equivalent — see the Rollup visualizer guide.

What should I compare against?

The same report id from the previous build. Bundle size is only meaningful as a delta, and a revision history gives you that without storing baselines yourself.

Can reviewers comment on a specific chunk?

Yes. Threads anchor to the rendered content, so 'moment got pulled in by the date helper' lands on that box in the treemap.

Share an esbuild metafile

esbuild will tell you exactly why your bundle is 400 KB heavier than last week — the metafile has every input, every output and the import chain that connects them. It just hands you JSON, and JSON is not an argument anyone wants to read during a pull request review.

Build the treemap

esbuild src/index.ts --bundle --minify \
  --outfile=dist/bundle.js --metafile=meta.json

npx esbuild-visualizer --metadata meta.json --filename stats.html

stats.html is standalone: the treemap, the sunburst toggle and the search box all travel inside the file.

Publish it

Drag stats.html into the app, or from CI:

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html stats.html \
        --arg title "Bundle — $GITHUB_REF_NAME" '{title: $title, html: $html}')"

Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so the treemap stays interactive at the URL — you can zoom into a chunk rather than squinting at a screenshot of one.

Size is a delta, not a number

"Bundle is 812 KB" means nothing on its own. "Bundle is 812 KB, up 106 KB since Tuesday, and the new weight is all in vendor-charts" is a review comment.

PATCH one report id per entry point and the revision history does that bookkeeping for you:

Revisions per build, so the previous treemap is one click away.
Anchored threads on the chunk that grew — "this is the whole icon set; we only use six" — next to the box that shows it. See commenting on HTML.
One id per branch if you want per-PR previews rather than a main-line trend.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A metafile for a very large app can push the rendered page toward the entry cap — visualize one entry point at a time.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a bundle report →