three-doctor

Diagnostics for Three.js, React Three Fiber, and Drei projects.

Three Doctor scans source, assets, package graphs, bundle reports, runtime probe reports, profiler data, and frame-capture style JSON to explain performance and production risks in Three.js applications.

Install

Run without installing:

npx three-doctor@latest .

Or install in a project:

npm install --save-dev three-doctor

Node.js 20 or newer is required.

Usage

three-doctor .
three-doctor . --verbose --fail-on none
three-doctor . --json
three-doctor . --score
three-doctor . --sarif
three-doctor . --annotations
three-doctor . --diff main
three-doctor . --staged
three-doctor . --why src/Scene.tsx:42
three-doctor . --explain runtime-high-draw-calls

Three Doctor auto-detects R3F, Drei-heavy R3F, vanilla Three.js, React apps with manual Three renderers, WebGPU source, and asset-only projects. You can override detection when needed:

three-doctor . --project r3f
three-doctor . --project drei
three-doctor . --project three
three-doctor . --project react-three
three-doctor . --project webgpu
three-doctor . --project assets

Runtime Checks

For R3F apps, mount the runtime probe from @three-doctor/r3f:

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

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

Then scan the running app:

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

If the app does not mount the probe, the CLI can use Playwright to auto-inject lightweight WebGL instrumentation:

three-doctor . \
  --runtime-url http://localhost:5173 \
  --auto-inject \
  --routes auto \
  --profile mobile-low \
  --interactions scroll,orbit \
  --capture-frame

Auto-inject reports renderer/frame/WebGL evidence, not scene-graph attribution. Mount <ThreeDoctorProbe /> when you need named object/subtree attribution. --capture-frame records lightweight WebGL command evidence; use --spector-report for full saved Spector.js capture analysis.

playwright is an optional peer dependency. Install it only for browser-based runtime collection:

npm install --save-dev playwright
npx playwright install chromium

Asset, Package, and Bundle Checks

Deep asset analysis inspects GLTF/GLB structure, image dimensions, estimated GPU texture memory, Meshopt/Draco geometry markers, KTX2/Basis texture markers, public asset reachability, cache-header risk, and asset budgets:

three-doctor . --assets deep
three-doctor . --assets deep --asset-report
three-doctor public/models/scene.glb --asset-report

Package and bundle analysis can catch duplicate Three ecosystem versions and heavy build outputs:

three-doctor . --bundle-report stats.json
three-doctor . --baseline-report three-doctor-main.json

CI

Typical pull-request command:

three-doctor . --diff main --annotations --sarif --fail-on warning

Useful CI outputs:

• --json emits the full machine-readable report.
• --json-compact emits compact JSON.
• --sarif emits SARIF 2.1.0.
• --annotations emits GitHub Actions annotations.
• --github-comment emits Markdown suitable for a PR comment.
• --baseline-report <file> compares against a prior Three Doctor JSON report.
• three-doctor report <report.json> derives annotations, SARIF, PR-comment Markdown, and GitHub output values from one JSON report.

Configuration

Create three-doctor.config.json in the project root:

{
  "failOn": "warning",
  "assets": {
    "enabled": true,
    "deep": false,
    "optimizedPatterns": ["**/*-optimized.glb", "**/*-v3.glb"]
  },
  "source": {
    "includeNonRuntime": false,
    "excludePatterns": ["tests/**", "scripts/**", "public/vendor/**"]
  },
  "staticAnalysis": {
    "adaptiveQualityPatterns": ["ScenePreviewPerformance", "getPreviewDpr"]
  },
  "ignore": {
    "rules": [],
    "files": [],
    "overrides": []
  }
}

Programmatic API

import { diagnose } from "three-doctor";

const report = await diagnose(".", {
  assetsMode: "deep"
});

console.log(report.score.score);
console.log(report.diagnostics);

Additional exports include RULES, DEFAULT_CONFIG, scanSourceText, scanAssets, analyzeRuntimeReport, analyzeSpectorReport, analyzeProfilerReport, scanPackageGraph, and report builders.

Related Packages

• @three-doctor/r3f provides the R3F runtime probe.
• @three-doctor/eslint-plugin exposes static diagnostics inside one ESLint bridge rule.
• @three-doctor/oxlint-plugin exposes static rule metadata and bridge config for Oxlint workflows.

License

MIT