Nub Charts

nubjs.com performance charts

Every performance figure on nubjs.com is a hand-generated SVG, not a charting library. They share one visual system with the homepage's <Bench> panel, and a new chart that does not match it looks broken next to the others.

The six rules (maintainer, 2026-09-08 and 2026-09-12)

The first charts drawn with this skill broke the first four, the next one broke the fifth, and the threadpool figures shipped with the sixth unbroken only because the maintainer asked for the axis to go, so they come before anything else.

1. One direction per figure. A figure is either "higher is better" or "lower is better", never both. A throughput and a latency from the same benchmark are two figures with two stems.
2. No footnotes and no caption line inside the image. A block of small text under the axis reads as a disclaimer, as if the number needed excusing. The fixture and the method go in the page caption, the tweet, or the benchmark README, never in the SVG.
3. The legend is left-aligned with the bar column, on its own line under the heading. Everything at the top of a figure starts at the same x; a right-justified legend under left-justified text reads as misplaced.
4. Cut the words. A heading of two or three words, a muted note of at most a version and the direction, row labels of one or two words. The post or the page supplies the context; the figure supplies the numbers. If a label needs a sentence, the row needs a better name.
5. The ink sits optically balanced in the frame: equal side margins, and generous ones. The eye compares the two horizontal margins first, so the bar column starts where the longest label ends and stops where the longest trailing text meets the padding — the renderer computes both from the rows (gutterFor, fitRight), never from a fixed x, and a label is never padded to fill a gutter. The padding is 56px at the sides and 30px top and bottom (PAD_X, PAD_Y), the sides wider on purpose: a landscape frame needs more side margin than vertical margin to look evenly padded. Both halves of the rule were corrected on the same day, 2026-09-12, on one two-row chart: first "TOO MUCH dead space on the left" (short labels in a gutter sized for long ones, 140px of nothing on the left against 40px on the right), then, once the margins matched at 22px, "it needs more space than that... optical balance" — centered ink that close to the edge reads as cramped. Check it on the raster: the leftmost label and the rightmost note should sit the same, comfortable distance from their edges.
6. A paired chart has no axis: no tick marks, no tick labels. Every bar already carries its value, so an axis repeats the numbers, and with a scale per group its ticks land at different positions from one group to the next, which reads as misaligned. Groups are separated by spacing alone (groupGap), which also closed the gap between the panels of the threadpool figure that read as "a little too much space between each chart" (maintainer, 2026-09-12: "just omit the x axis numbers altogether, and ticks"). The unit therefore lives in the value label (66 req/s, 1,763 Mloops/s), never in a tick.

A chart is the last step, never the first. The number comes from a benchmark under tests/bench/ that survives the methodology in AGENTS.md and the benchmarking skill; the chart only draws it. A figure built on numbers from a loaded machine is worse than no figure, because it ships a claim nobody will re-check.

Where things live

The workflow

1. Write or find the benchmark in tests/bench/. It must print a machine-readable line per measurement — the runtime scripts print one ROW {…} per cell — so the generator never has numbers typed into it by hand. A run worth keeping is saved as results/<date>.json with the machine, the Node version and every per-round value; the generator reads that file. Typing numbers into the generator is not acceptable, because the figure then has no provenance.
2. Run it on the latest Node, on a quiet machine. A figure measured on an old Node line reads as if the win needed one; an augmentation that applies everywhere is measured on the current major (26 today), and the heading does not name a version. Only a version-gated augmentation is measured on the line it gates, and then the heading names that line, because the claim is about it. The dev Mac is never quiet; a runtime benchmark goes to an idle spot VM through remote-build --job adhoc (the script runs at the repo root with NUB_BIN set). For an install benchmark, uptime first and follow the benchmarking skill's load gate. A Windows-only behavior is measured on a real windows-latest runner through a dispatch-only workflow that uploads the results JSON as an artifact — tests/bench/windows-dispatch/ and .github/workflows/bench-windows-dispatch.yml are the template — and the run is committed under results/ before anything is drawn. A number remembered from a PR body, a code comment or a release post is not provenance, however well it was measured at the time: the Windows dispatch figure re-measured 95.6 → 35.8 ms as 92.9 → 19.9 ms on the current release, and only the saved run can say which is true today.
3. Write a generator that reads the saved run and calls scripts/chart.mjs. Keep it in your scratch directory.
4. Rasterize and look at it. rsvg-convert -z 2 -b '#faf7f0' in.svg -o out.png, then read the PNG. Every layout bug in "Traps" below is invisible in the SVG source and obvious in the render. Check the dark theme too, with -b '#100f0d'. Encode Sans is installed on the dev Mac, so the raster uses the site's face; the mono falls back to Menlo.
5. Emit the triple into site/public/blog/ and wire it into the MDX.

Trust the numbers before you draw them

A chart makes a number look settled, so check it is before you commit it to a figure.

• Run several rounds and look at the spread before picking a statistic. For a time, the per-cell minimum across rounds is the closest estimate of the noise floor. For a throughput under a load generator, the rounds cluster and the mean is the honest figure; state the round count in the page caption. One round is an anecdote.
• Interleave the conditions. Alternate node and nub on every round rather than running all of one then all of the other, so a drift in the box lands on both sides equally. The threadpool file-read question was settled only by an interleaved rerun: two back-to-back rounds read 4–8% apart, five interleaved rounds read 1.9%.
• Watch which side of a comparison is unstable. When the ratio swings but one series is rock-steady, the noise is entirely in the other one, and that usually names the mechanism.
• Look for a control inside your own data. nub --node in the same run is plain Node with nothing injected; if it does not match node, the harness is measuring something other than the augmentation. node with the flag set by hand is the other control: if nub does not match it, the augmentation is not what is being measured.
• Say what the load generator shared. autocannon on the same box competes with the server for cores, and a route bound by the event loop can read a couple of percent lower when the pool has more threads to schedule. Include the routes that do not gain; they are what makes the routes that do credible.
• Ask whether the win is a ratio or a constant. Subtract the two series per row. A roughly constant difference means a fixed cost is being skipped and the multiplier is a statement about the cheapest row; a difference that scales with the row means the work itself got faster. These are different claims and the prose must say which.
• Check the mechanism in the source, not from the shape of the graph. A caption built on the obvious story is the failure mode; read the code path that moved before writing it.

The three forms

pairedChart — the same measurement under two conditions, one bar each per row: a track-colored bar for plain node, an ember bar for nub. No axis is drawn (rule 6); groups carry their own scale and unit, so two magnitudes of the same direction can share a figure without sharing a scale, and a figure never mixes directions. This is the form for a runtime augmentation, where the subject is often the LARGER number: req/s under nub against req/s under node. Sort rows by the size of the effect when the effect is the story, by a natural order (the routes as listed in the benchmark) when the spread is.

overlapChart — one measurement against another on a shared axis where the subject is the SMALLER number. The slower series is a track; the faster one is an ember bar drawn inside it, so the gap between them is the win. Right for a time under two conditions (cold vs warm, before vs after). Sort by the ember bar, not the track: ember is the subject, and a subject series that jumps around is the first thing a reader notices. Never use it for a throughput: the subject bar would cover the track and the comparison vanishes.

rankedChart — one value per row, longest first, optionally split into titled groups. This is the form for cross-tool comparisons, where the bars measure different things that have no pairing. Nub's own rows are highlighted; everything else is the track color.

Pick by whether the two numbers are the same measurement under two conditions. If they are and the subject is a time, overlap them; if the subject can be the larger number, pair them; if they are not the same measurement, rank them.