Chapter 812: Debugging JavaScript (Manual)

Core Idea

General JavaScript debugging habits — browser devtools, console, on-screen overlays, query parameters — that resolve most three.js issues, since most bugs beginners hit are ordinary JavaScript problems rather than three.js-specific ones.

Key Concepts

• Browser devtools console: read every warning and error message first; they usually point straight at the problem (e.g. a typo like importing "threee" instead of "three").
• Disable browser cache while developing: prevents the browser from serving stale files instead of your latest edits.
• console.log / console.error: logging an object (e.g. a loaded glTF scene) lets you expand and inspect it interactively in the console; console.error adds a stack trace.
• On-screen debug overlays: HTML elements positioned over the canvas, or a "clearing logger" that only shows the current frame's values, for real-time data like FPS or object positions.
• Query parameters: reading ?debug=true from the URL to toggle debug UI without changing shipped code.
• Matrix/NaN checks: a common root cause category — inspect camera and object world/projection matrices in the debugger for NaN or out-of-scale values.

Code Examples

const logger = new ClearingLogger(document.querySelector("#debug pre"));

function render(now) {
  now *= 0.001;
  const deltaTime = now - then;
  then = now;

  logger.log("fps:", (1 / deltaTime).toFixed(1));
  // ...update and log per-object state each frame...

  renderer.render(scene, camera);
  logger.render();
  requestAnimationFrame(render);
}

• What it demonstrates: a "clearing logger" pattern that displays only the current frame's debug values instead of spamming the console.

Key Takeaways

1. Always read devtools console warnings/errors first — they usually point directly at the bug.
2. Disable the browser cache while developing so you're not debugging stale files.
3. A frame-cleared logger overlay is a lightweight way to show real-time values (FPS, positions) without flooding the console.
4. Query parameters like ?debug=true let you toggle debug tooling without touching your shipped code path.
5. NaN values in camera or object matrices are a common, easy-to-check root cause of "nothing renders" bugs.

Connects To

• PerspectiveCamera: whose matrices are a common target of the NaN check described here.
• MeshBasicMaterial / GridHelper: used to build a minimal known-good debug scene.