@three-doctor/r3f

Runtime probe for Three Doctor in React Three Fiber apps.

The probe samples renderer, scene, frame-loop, memory, raycasting, matrix-update, animation, interaction, and visibility metrics. The Three Doctor CLI can read these metrics from window.__THREE_DOCTOR__.getReport() when run with --runtime-url.

Install

npm install --save-dev @three-doctor/r3f three-doctor

Peer dependencies:

• @react-three/fiber >=8
• react >=18
• three >=0.150

Usage

Mount the probe inside an R3F Canvas:

import { Canvas } from "@react-three/fiber";
import { ThreeDoctorProbe } from "@three-doctor/r3f";

export function App() {
  return (
    <Canvas dpr={[1, 2]}>
      <ThreeDoctorProbe />
      <Scene />
    </Canvas>
  );
}

Run the CLI against the running app:

three-doctor . --runtime-url http://localhost:5173

Options

<ThreeDoctorProbe
  id="main"
  sampleSize={240}
  enabled={process.env.NODE_ENV !== "production"}
  trackMatrixUpdates
  trackRaycasts
  trackAnimations
/>

• id labels the canvas/report.
• sampleSize controls how many frames are retained for frame timing summaries.
• enabled disables collection when false.
• trackMatrixUpdates instruments Three object matrix update methods.
• trackRaycasts instruments THREE.Raycaster.
• trackAnimations instruments THREE.AnimationMixer.

Reading a Report Manually

const report = window.__THREE_DOCTOR__?.getReport();

Save that JSON and merge it later:

three-doctor . --runtime-report runtime-report.json

Production Guidance

The probe is designed for development, QA, and CI profiling. Gate it behind a development flag if you ship the same code path to production:

{import.meta.env.DEV ? <ThreeDoctorProbe /> : null}

License

MIT