threejs-debug-view

threejs-debug-view exposes named debug views for the buffers your scene already produces: beauty, normals, depth, material channels, wireframe, lighting-only, reflection-only, overlap, and shader cost.

Native

Import from threejs-debug-view when you own the WebGPU render loop. You get view definitions, render planning, and runtime helpers such as createDebugPipelineRuntime and createDebugViewportRenderer. No React, R3F, or Leva required.

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)
}

Native install · Native Runtime

R3F

Optional React Three Fiber adapter. Import from threejs-debug-view/r3f for DebugViewLayer — built-in views, Leva controls, and DOM labels/legends inside a <Canvas>.

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

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

R3F install · R3F guide

Keep debug views behind a dev flag unless you intentionally expose them in production.

Live demo

Use the panel to switch views, layouts, and pane assignments. Try the Overlap and Lights scene tabs for measured overlap and light overlap. On Shader Complexity or Measured Overlap, click the viewport to sample a pixel and move the legend marker.

Open the demo in a new tab

Note

The demo requires browser WebGPU support. When native WebGPU is unavailable, the app stops instead of falling back to WebGL.

Built-in views

DEFAULT_DEBUG_VIEWS ships sixteen named sources. Override and heatmap passes are demand-driven — they render only when the active view or layout needs them.

Source	Mode	What it shows
beauty	passthrough	Final lit color
normal	passthrough	View-space geometry normals
depth	depth	View-space depth
albedo	passthrough	Base color without lighting
materialNormal	passthrough	Material normal map output
emissive	passthrough	Emissive color
roughness	passthrough	Packed scalar (R)
metallic	passthrough	Packed scalar (G)
ao	passthrough	Packed scalar (B); material AO, not SSAO
opacity	passthrough	Packed scalar (A)
wireframe	passthrough	Wireframe override pass
lightingOnly	passthrough	Neutral lighting-only override
reflectionOnly	passthrough	Reflection-only override
overdraw	heatmap	Measured contributor layer count
lightComplexity	heatmap	Light overlap (v1 analytic counter)
shaderCost	heatmap	Shader-cost estimate (not native GPU counters)

See Built-in Views · Overlap & light diagnostics · Shader cost.

Custom debug view

Add a TSL node, or use createCustomDebugView() with a stable id when view instances may be recreated:

import { float, vec4 } from "three/tsl"
import { createCustomDebugView, DEFAULT_DEBUG_VIEWS } from "threejs-debug-view"

const fresnelView = createCustomDebugView({
  id: "shader:fresnel",
  label: "Fresnel",
  node: vec4(float(1), float(0), float(0), float(1)),
})

const views = [...DEFAULT_DEBUG_VIEWS, fresnelView]
// Pass `views` into createDebugRenderPlan() — or into R3F DebugViews when using the adapter.

Custom Debug Views · Presentation routing

Quality gates

Gate	Command	What it checks
Typecheck	pnpm typecheck	TypeScript across library + demo
Unit tests	pnpm test	Vitest (render plans, views, helpers)
Library build	pnpm build	ESM dist/ + declaration emit
npm surface	pnpm pack:check	Tarball contains only publishable files; bundle badge
Docs build	pnpm docs:build	This Starlight site compiles
Full verify	pnpm verify	All of the above
E2E demo	pnpm test:e2e	Playwright against the Vite demo (WebGPU required)

Deployment · Contributing gates in the repo README