{"id":12073,"library":"stats.js","title":"Stats.js Performance Monitor","description":"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.","status":"active","version":"0.17.0","language":"javascript","source_language":"en","source_url":"https://github.com/mrdoob/stats.js","tags":["javascript","performance","fps","stats"],"install":[{"cmd":"npm install stats.js","lang":"bash","label":"npm"},{"cmd":"yarn add stats.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add stats.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Stats = require('stats.js'); // CommonJS import\nvar stats = new Stats(); // Global access pre-r17","symbol":"Stats","correct":"import Stats from 'stats.js'"},{"note":"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.","symbol":"Stats","correct":"import Stats from 'stats.js/src/Stats'"}],"quickstart":{"code":"import Stats from 'stats.js';\n\nconst stats = new Stats();\nstats.showPanel( 0 ); // 0: fps, 1: ms, 2: mb, 3+: custom\nstats.dom.style.position = 'fixed';\nstats.dom.style.top = '0px';\nstats.dom.style.left = '0px';\nstats.dom.style.zIndex = '10000';\ndocument.body.appendChild( stats.dom );\n\nfunction animate() {\n  stats.begin();\n\n  // Your monitored code goes here\n  // For example, a simple loop or animation logic\n  for (let i = 0; i < 100000; i++) {\n    Math.sin(i);\n  }\n\n  stats.end();\n\n  requestAnimationFrame( animate );\n}\n\nrequestAnimationFrame( animate );","lang":"javascript","description":"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."},"warnings":[{"fix":"Update import statements to `import Stats from 'stats.js';`. Ensure your build environment supports ES modules or use a bundler like Webpack/Rollup.","message":"Version 0.17.0 (r17) converted the library to an ES module. This change breaks existing CommonJS `require()` or global `Stats` usage.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"For Chrome, run the browser with the `--enable-precise-memory-info` flag. Browser support for detailed memory stats can vary.","message":"The 'MB' (memory) panel often requires specific browser flags to function correctly and provide precise memory information, particularly in Chrome.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.17.0"},{"fix":"Instead of the bookmarklet, embed `stats.js` via npm, a CDN (like unpkg or jsdelivr), or host it locally for reliable access.","message":"Direct embedding via a bookmarklet loading from `rawgit.com` might encounter issues as `rawgit.com` is no longer maintained.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your code from `var stats = new Stats();` to `import Stats from 'stats.js'; const stats = new Stats();`.","cause":"Attempting to use `Stats` globally after upgrading to v0.17.0 (r17) without using ES module imports.","error":"Uncaught ReferenceError: Stats is not defined"},{"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.","cause":"Trying to use `require('stats.js')` in an environment that only supports ES modules or in a browser without a CommonJS bundler.","error":"require is not defined"},{"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';`.","cause":"The `stats` object was not properly initialized or is `undefined` when trying to access `stats.dom`.","error":"TypeError: Cannot read properties of undefined (reading 'dom')"}],"ecosystem":"npm"}