Quick Start

Both paths use the same WebGPU + TSL runtime. Start with the native root export; add R3F only when you want React wiring, Leva, and DOM labels/legends.

Native

For a vanilla Three.js WebGPU app:

pnpm add threejs-debug-view three

Wire the native runtime into your frame loop:

import {
  DEFAULT_DEBUG_VIEWS,
  createDebugRenderPlan,
  createDebugPipelineRuntime,
  createDebugViewUniforms,
  resolveDebugViewLayout,
  updateDebugViewUniforms,
} from "threejs-debug-view"
import { WebGPURenderer } from "three/webgpu"

const views = DEFAULT_DEBUG_VIEWS
const layout = resolveDebugViewLayout("single")
const plan = createDebugRenderPlan(views, 0, layout)
const uniforms = createDebugViewUniforms()

const runtime = createDebugPipelineRuntime(
  scene,
  camera,
  plan,
  layout,
  renderer as WebGPURenderer,
  uniforms,
)

function animate() {
  updateDebugViewUniforms(uniforms, plan.activePipelineView, layout, plan.pipelineViews.length, 1)
  runtime.pipeline.render()
  requestAnimationFrame(animate)
}

Next: Native Runtime for multi-pane layouts, viewport scaling, and requiresViewportRuntime.

R3F

Optional adapter for React Three Fiber — add the peers:

pnpm add threejs-debug-view three react react-dom @react-three/fiber @react-three/drei leva

Batteries included

import { DebugViewLayer } from "threejs-debug-view/r3f"

function DebugLayer() {
  if (!import.meta.env.DEV) return null
  return <DebugViewLayer />
}

Mount inside <Canvas>. Leva mounts on document.body automatically unless you set showLeva={false}.

Next: R3F guide for Leva placement, props, and what ships on npm.

Bring your own controls

import { DEFAULT_DEBUG_VIEWS, getDebugViewLabels } from "threejs-debug-view"
import { DebugViews, useDebugViewsControls } from "threejs-debug-view/r3f"

const controls = useDebugViewsControls({
  viewLabels: getDebugViewLabels(DEFAULT_DEBUG_VIEWS),
})

<DebugViews views={DEFAULT_DEBUG_VIEWS} {...controls} />

Pin a specific view

const emissiveIndex = DEFAULT_DEBUG_VIEWS.findIndex((view) => view.source === "emissive")

<DebugViews
  views={DEFAULT_DEBUG_VIEWS}
  activeView={emissiveIndex}
  layout="single"
  showLabels
/>

The repo demo supports URL params such as ?debugView=emissive, ?scene=overdraw&debugView=overdraw, and ?scene=lights&debugView=lightComplexity. Use the Overlap and Lights scene tabs in the demo shell. See Overlap & Light Diagnostics. For a fixed breakdown capture preset, open /?capture=social&scene=overdraw while pnpm dev is running.

Verify locally

pnpm typecheck
pnpm test
pnpm test:e2e

pnpm test:e2e needs Chromium with native WebGPU. CI fails if the demo cannot start WebGPU there.