GitHub 42
Skip to content

Bundle

A bundle size report in Markdown, read from two builds.
Upgrade the dashboard to ECharts 5.5
9.7 kB+4.3 kB
every page, was 5.4 kB before
before
afterechartszrender
Every page up 4.3 kB (79.0%): echarts, zrender moved into every page; lodash-es added
Lazy 0.8 kB (−4.8 kB) · gzip -9 · brotli 11 · 1 chunk without a sourcemap
What's in the bundle5 packages · 5 chunks
Every page
echarts@vue/runtime-corezrenderapp codedate-fns
Lazy
echartszrender
Area is gzip size.
::bundle{before="main" after="pr" title="Upgrade the dashboard to ECharts 5.5"}
::
md
  • Reads the builds itself: each build folder's chunks, measured with gzip -9 and brotli 11, and their sourcemaps for package names. Nothing to paste or keep in sync.
  • Splits what every page loads from what loads later: the entry, its static imports, and Nuxt's default layout, against routes and import().
  • Draws the bars in neutrals and marks only what changed: what the new build added to every page is dark, and what it dropped is hatched, with the package's name under it.
  • Says the change in one sentence for screen readers, so the number and the reason read without the picture.
  • Keeps a treemap of the new build behind a native <details>, with a removed package at its old size. No script.

Point before and after at two builds of the same app. Paths are read from the document's folder, or from the root when they start with /.

Bundle size
9.7 kB+4.3 kB
every page, was 5.4 kB before
before
afterechartszrender
Every page up 4.3 kB (79.0%): echarts, zrender moved into every page; lodash-es added
Lazy 0.8 kB (−4.8 kB) · gzip -9 · brotli 11 · 1 chunk without a sourcemap
What's in the bundle5 packages · 5 chunks
Every page
echarts@vue/runtime-corezrenderapp codedate-fns
Lazy
echartszrender
Area is gzip size.
::bundle{before="main" after="pr"}
::
md

Each path is a build's client output folder, such as dist for Vite or .output/public/_nuxt for Nuxt, which the block measures while it parses. Every JavaScript file under it counts, so leave server code out.

Note

A build folder needs sourcemaps to show packages, such as Vite's build.sourcemap: "hidden". Without them the block shows chunks.

Use the title prop to name the report in its header. It also names the figure for screen readers. Without it, the header reads "Bundle size".

Upgrade the dashboard to ECharts 5.5
9.7 kB+4.3 kB
every page, was 5.4 kB before
before
afterechartszrender
Every page up 4.3 kB (79.0%): echarts, zrender moved into every page; lodash-es added
Lazy 0.8 kB (−4.8 kB) · gzip -9 · brotli 11 · 1 chunk without a sourcemap
What's in the bundle5 packages · 5 chunks
Every page
echarts@vue/runtime-corezrenderapp codedate-fns
Lazy
echartszrender
Area is gzip size.
::bundle{before="main" after="pr" title="Upgrade the dashboard to ECharts 5.5"}
::
md

Use the src prop instead of before and after to show one build without a comparison: what every page loads, and the treemap of what the build holds.

Bundle size
9.7 kB
every page · lazy 0.8 kB
Every page
echartszrenderapp codedate-fns
Lazy
date-fnslodash-esapp code
5 packages · 5 chunks
Area is gzip size · gzip -9 · brotli 11 · 1 chunk without a sourcemap
::bundle{src="pr"}
::
md

Evidence for a performance pull request

Section titled "Evidence for a performance pull request"

Keep the base branch's build next to the new one, then put the block in the pull request's evidence, as Before and after evidence describes.

git worktree add ../main origin/main
(cd ../main && pnpm install && pnpm build)
cp -r ../main/dist .bundle/main
pnpm build
::bundle{before=".bundle/main" after="dist" title="Replace Moment with Temporal"}
::
md

Point the block at .output/public/_nuxt after nuxi build. Nuxt loads the default layout with import(), but every page that uses it waits for it, so the block counts the layout and its imports toward every page and says so in the footer.

PropDefaultDescription
before—The build to compare from: its output folder, such as dist.
after—The build to compare to, in the same forms as before.
src—One build to show without a comparison, in place of before and after.
title"Bundle size"Shown in the header, and names the figure for screen readers.

Pass options under bundle in comarkUi(), or to bundle() alone. In comarkUi(), a ::bundle block reads no builds until you pass options, such as comarkUi({ bundle: { root: "." } }).

OptionDefaultDescription
root"."The folder a path can't leave, as in comark-include.
base""The document's folder under root, where relative paths start.
readReads from diskTakes a path under the root and returns the file's text.
listLists from diskTakes a folder under the root and returns its files. Measuring also needs Node's zlib, so the block reads builds only in Node.

Every .js and .mjs file in the folder, with its gzip -9 and brotli 11 size, its import and import() of other chunks, and its sourcemap's sources, which name the packages. A chunk without a sourcemap counts as the app's own code, and the footer says how many there are. A package found on one side only isn't called added or removed when the other side contains chunks without a sourcemap: compressed size cannot establish its absence.

The entries come from Vite's .vite/manifest.json, else the <script type="module"> tags of index.html, looked for in the folder and its parent. Without either, the block reads them from the graph: a chunk loaded by import() or as a worker is lazy, and so is the code it needs that the chunk loading it doesn't, even when it imports code back from the entry. When the graph can't tell, the block reports it instead of guessing. A guess can still be wrong when the entry's import() calls sit in a chunk of their own, since that graph reads the same as a lazy chunk importing the entry back, so keep the index.html or the manifest.

Every page is the entries and their static imports, plus Nuxt's default layout and its imports when the build has one. A build with several entries, such as a multi-page app, counts them all. Everything else loads later. A package's size is its share of its chunks' characters, applied to the chunks' gzip and brotli sizes. Sizes are in kB of 1,000 bytes, as the build tools print them.

The plugin adds these problems to meta.issues, as Validation describes:

  • A block with no build, or with only one of before and after.
  • A block with src and before or after together.
  • A path that is a URL, leaves the root, or doesn't exist.
  • A path that is a file, a folder with no JavaScript, or a build whose entry chunk it can't find.
  • Text inside the block. The block drops it.
  • A prop it doesn't read. It's ignored.

Each issue names the block and the fix, and has its own rule in Doctor:

`::bundle` 1: it has `after` but no `before`. Give both builds, or use `src` for one.
`::bundle` 2: "dist/asets" doesn't exist. It resolved to "dist/asets" under the root; check the path or `base`.
txt

comark-ui installs and registers comark-bundle. To use it alone, install it with Comark and a renderer:

pnpm add comark @comark/html comark-bundle

Register the plugin with the folder it may read, and pass the renderer's components:

import { createHtmlRenderer } from "@comark/html";
import bundle, { components } from "comark-bundle/html";

const render = createHtmlRenderer({ plugins: [bundle({ root: "." })], components });
ts

For Vue, React, or Svelte, import from comark-bundle/vue, comark-bundle/react, or comark-bundle/svelte. The components add the styles on mount. Import comark-bundle/style.css with your styles so a server-rendered page doesn't shift. Renderers covers using it with other plugins.

The report sits in a bordered card with a quiet header, like Diff. The badge is red when every page grew and green when it shrank, from the status colors; the bars and the treemap are neutral. The rules sit in a comark CSS layer, so any plain rule of yours wins.

The report reads these shared tokens:

TokenUsed for
--comark-backgroundThe card
--comark-foregroundThe number, mixed into the bars, the tiles, and the labels
--comark-mutedLabels, the muted footer line, and the icon
--comark-borderThe card's edge, the header, and the disclosure
--comark-accentThe header, and a hovered disclosure
--comark-successThe badge of a smaller total
--comark-dangerThe badge of a bigger total
--comark-ringThe disclosure's focus ring
--comark-radiusThe card's corners
--comark-fontThe text

Set them on .cbr:

VariableDefaultUsed for
--cbr-better, --cbr-worseSuccess and danger, mixed toward the textThe badge's text
--cbr-restThe text at 16%The part of each bar that didn't change
--cbr-inkThe text at 78%What the new build added, in a bar and in the treemap
--cbr-textThe text at 72%The labels and the names under the bars
--cbr-tileThe text at 6%A package's tile
ClassElement
.cbrThe card, a <figure>
.cbr-head, .cbr-titleThe header and its title
.cbr-big, .cbr-pillThe number and its badge; [data-verdict] is better, worse, or same
.cbr-bar, .cbr-segA build's bar and its parts; [data-kind] is rest, removed, moved-out, added, or moved-in
.cbr-foot-1, .cbr-foot-2The change in words, for screen readers, and the footer's muted line
.cbr-moreThe disclosure, a <details>
.cbr-tileA treemap tile; [data-kind] as on .cbr-seg, plus changed and same
.cbr {
  --cbr-ink: oklch(0.55 0.15 260);
}
css