jank.js
v1.0.1
Published
An embeddable performance monitor for browser games and interactive graphics, with nothing else to install.
Maintainers
Readme
___ ________ ________ ___ __ ___ ________
|\ \|\ __ \|\ ___ \|\ \|\ \ |\ \|\ ____\
\ \ \ \ \|\ \ \ \\ \ \ \ \/ /|_ \ \ \ \ \___|_
__ \ \ \ \ __ \ \ \\ \ \ \ ___ \ __ \ \ \ \_____ \
|\ \\_\ \ \ \ \ \ \ \\ \ \ \ \\ \ \|\ \\_\ \|____|\ \
\ \________\ \__\ \__\ \__\\ \__\ \__\\ \__\ \________\____\_\ \
\|________|\|__|\|__|\|__| \|__|\|__| \|__|\|________|\_________\
\|_________|jank.js
A performance monitor that runs inside your browser game. It shows frame pacing, the time spent in each system you name, and the slow frame with the frames around it. Record what happened, compare two versions of your workload, and read the results in a viewer that never leaves your machine.
Nothing to install beyond the package: its small UI runtime is bundled. ~4.6 KB core, ~64 KB with the panel, gzipped; the viewer loads only when you open it. Nothing is uploaded, estimated or smoothed. Missing data stays missing.
Install
npm install jank.jsUse
Call it from your own frame loop:
import { createDiagnostics } from "jank.js";
import { createPerformancePanel } from "jank.js/panel";
const monitor = createDiagnostics();
const panel = createPerformancePanel({ shell: document.body, monitor });
const physics = monitor.register("physics", "Physics", () => ({
bodies: world.bodyCount,
}));
const drawing = monitor.register("drawing", "Drawing");
function frame(at) {
monitor.beginFrame(at);
panel.refresh(at);
const start = performance.now();
const scope = physics.begin();
stepPhysics(); // your update
physics.end(scope);
const drawn = performance.now();
const drawScope = drawing.begin();
drawScene(); // your render
drawing.end(drawScope);
monitor.endFrame(drawn - start, performance.now() - drawn);
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);For a known pause, call monitor.resetFrame() to discard the unfinished interval without clearing the recording; see visibility handling.
Mark moments with monitor.event("Scene changed"). Only what your app supplies is shown; sections without a source stay hidden or read as unavailable, never as zero.
The panel
It floats in a corner of the viewport, in its own Shadow DOM, so your styles and its styles cannot touch. Three sizes, all collecting: one line for a playtest, a mini HUD, the full panel when something stutters. It's built for desktop widths.
CAPTURE records manually, or automatically on a spike, a sustained slowdown or a whole episode, keeping the frames before and after. LOADING puts your load stages on one axis, with cold and repeat runs compared. COMPARE runs an A/B test.
A/B comparison
Report two variants and how to switch between them, and the panel runs them in alternating pairs with warm-up, then gives a verdict for CPU, GPU and frame time:
const shadows = getShadows();
const panel = createPerformancePanel({
shell: document.body,
monitor,
comparison: {
change: "shadows",
variants: {
A: { label: "Shadows on", settings: { shadows: true } },
B: { label: "Shadows off", settings: { shadows: false } },
},
activate: (variant) => setShadows(variant === "A"),
restore: () => setShadows(shadows),
},
});Other settings that differ are flagged as confounds. A verdict means the range across pairs excludes zero. It isn't a significance test and has no minimum size, so read the size of the difference beside it. Stopped and failed runs keep their finished trials.
The viewer
Open a saved capture from the panel, or use jank.js/viewer.html: one self-contained file. Choose a recording or comparison to step through every frame, its CPU and GPU lanes, its counters and its evidence.
Adapters
Optional, and none bundles a renderer. jank.js/adapters/three reads renderer.info counters. jank.js/adapters/three-webgpu and jank.js/adapters/webgl2 time GPU passes: pass the source they return as gpu. jank.js/adapters/three-host adds renderer errors, instance and loading observers for Three.js hosts. jank.js/gpu gives frame-linked GPU evidence for recordings. jank.js/agent adds window.jank, so scripts and agents can record and read a short report (guide). The agent interface and jank analyze are a prototype, and their report schema may still change.
Upgrading from 0.3
createDiagnostics and the rest of the core API, the recording format and existing recordings keep working. The panel and viewer are new:
-import { createDiagnostics, createPerformanceTray } from "jank.js";
-import "jank.js/style.css";
+import { createDiagnostics } from "jank.js";
+import { createPerformancePanel } from "jank.js/panel";
-const tray = createPerformanceTray({ shell, monitor, gpu });
+const panel = createPerformancePanel({ shell, monitor, gpu });Call panel.refresh(at) straight after monitor.beginFrame(at), and panel.destroy() instead of tray.dispose(). See the changelog for what was removed.
Docs
User manual · Integration · Data model · Measurements and limits · Overhead · GPU measurements · Three.js playground · Architecture
See it catch something in Junktro, a deliberately heavy CRT desktop.
Develop
pnpm dev # the playground and review pages
pnpm check # lint, types, unit tests and builds
pnpm test:package # the packed tarball in a clean consumer
pnpm test:e2e # the panel, viewer and built package in Chromium, Firefox and WebKit
pnpm test:e2e:gpu # real GPU timing in Chrome on your hardware
pnpm docs:captures # retake the README images from a real run (needs Chrome and ffmpeg)
pnpm bench # per-frame overhead of the built panel in headless ChromiumRead CONTRIBUTING.md and SECURITY.md.
MIT © 2026 Isaac Johnson, released by Junklab. Third-party notices.
