Stats.js Performance Monitor

Common errors

• Uncaught ReferenceError: Stats is not defined

  cause 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

  cause 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')

  cause 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';`.

Warnings

• breaking Version 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.
• gotcha The '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.
• gotcha Older 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.
• deprecated Direct 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.

Install

• npm install stats.js npm
• yarn add stats.js yarn
• pnpm add stats.js pnpm

Imports

• Stats
  wrong:

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

  correct:

  import Stats from 'stats.js'

  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.

Quickstart

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 );