stats.js

library0.17.0jsnpmunverified

Stats.js is a lightweight, client-side JavaScript performance monitor designed to display real-time metrics such as Frames Per Second (FPS), milliseconds per frame (MS), and allocated memory (MB) directly in the browser. The current stable version, 0.17.0 (r17), introduced a significant change by converting the library to an ECMAScript module. While its release cadence has historically been irregular, with key updates like `r16` adding `devicePixelRatio` support and `r15` reverting to a more efficient canvas-based rendering, `r17` represents the most recent major shift in its distribution format. It differentiates itself through its minimal footprint and immediate visual feedback, making it an excellent tool for quick performance profiling during development without requiring complex tooling integrations.

observability testing

npm install stats.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STATS.JS

stats.js

observabilityjavascriptv0.17.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Stats

✓ import Stats from 'stats.js'

✗ const Stats = require('stats.js'); // CommonJS import var stats = new Stats(); // Global access pre-r17

Since version 0.17.0 (r17), stats.js is distributed as an ECMAScript module and should be imported using the ESM syntax. Older versions (pre-r17) exposed `Stats` globally or via CommonJS.

Stats

✓ import Stats from 'stats.js/src/Stats'

For direct import of the source file or when working with bundlers that resolve 'exports' differently, you might need to target the source directly, though the main entry point is preferred.

This example demonstrates how to initialize Stats.js, append it to the document body, and integrate it into an animation loop to monitor performance metrics like FPS.

import Stats from 'stats.js'; const stats = new Stats(); stats.showPanel( 0 ); // 0: fps, 1: ms, 2: mb, 3+: custom stats.dom.style.position = 'fixed'; stats.dom.style.top = '0px'; stats.dom.style.left = '0px'; stats.dom.style.zIndex = '10000'; document.body.appendChild( stats.dom ); function animate() { stats.begin(); // Your monitored code goes here // For example, a simple loop or animation logic for (let i = 0; i < 100000; i++) { Math.sin(i); } stats.end(); requestAnimationFrame( animate ); } requestAnimationFrame( animate );

Debug

Known issues

breakingVersion 0.17.0 (r17) converted the library to an ES module. This change breaks existing CommonJS `require()` or global `Stats` usage.

fix

Update import statements to `import Stats from 'stats.js';`. Ensure your build environment supports ES modules or use a bundler like Webpack/Rollup.

affects: >=0.17.0

gotchaThe 'MB' (memory) panel often requires specific browser flags to function correctly and provide precise memory information, particularly in Chrome.

fix

For Chrome, run the browser with the `--enable-precise-memory-info` flag. Browser support for detailed memory stats can vary.

affects: All versions

gotchaOlder versions (r3, r15) made changes to default positioning and rendering technology (DOM vs. Canvas). While generally backward compatible, these could subtly affect integration in complex layouts.

fix

Always explicitly set `stats.dom.style.position`, `top`, `left`, and `zIndex` if precise control over the monitor's placement is needed, as default styles might change across releases.

affects: <0.17.0

deprecatedDirect embedding via a bookmarklet loading from `rawgit.com` might encounter issues as `rawgit.com` is no longer maintained.

fix

Instead of the bookmarklet, embed `stats.js` via npm, a CDN (like unpkg or jsdelivr), or host it locally for reliable access.

affects: All versions

Errors

Common errors & fixes

Uncaught ReferenceError: Stats is not defined

Attempting to use `Stats` globally after upgrading to v0.17.0 (r17) without using ES module imports.

fix

Change your code from `var stats = new Stats();` to `import Stats from 'stats.js'; const stats = new Stats();`.

require is not defined

Trying to use `require('stats.js')` in an environment that only supports ES modules or in a browser without a CommonJS bundler.

fix

If using v0.17.0 or newer, use `import Stats from 'stats.js';`. If targeting older versions in a browser, ensure `stats.js` is loaded via a `<script>` tag or a compatible bundler.

TypeError: Cannot read properties of undefined (reading 'dom')

The `stats` object was not properly initialized or is `undefined` when trying to access `stats.dom`.

fix

Ensure `new Stats()` is called and assigned to the `stats` variable before attempting to access its properties. Check for correct `import Stats from 'stats.js';`.

Upgrade

Version history

0.17.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mrdoob/stats.js ↗

packagehttps://www.npmjs.com/package/stats.js ↗

homepagehttps://stats.js.org ↗