Threejs R3f

Version-sensitive. Every API name, SDK gate and browser-support claim below was verified on 2026-09-08 against primary sources. What against, and when, is in _jutsu/VERSIONS.md. If that date is old, re-verify before acting on a version number.

Three.js & React Three Fiber

3D on the web. Three.js is the engine, R3F is the React renderer. Concise rules here. Deep-dive in references/.

Versions: three r185 (0.185.x) · @react-three/fiber 9.x · @react-three/drei 10.x · @react-three/postprocessing 3.x. R3F 9 is React 19 only - its declared peer range is react / react-dom >=19 <19.3 (drei 10 asks ^19). React 18 projects must stay on R3F 8 + drei 9. Check the installed React major before scaffolding. Renderers: WebGLRenderer is still R3F's default. WebGPURenderer + TSL is shipped (not flagged) and self-falls-back to WebGL 2, but three's docs call it "the new alternative of WebGLRenderer", not the default. Opt in with an async gl callback:

tsxCopy code
import * as THREE from 'three/webgpu'
<Canvas gl={async (props) => { const r = new THREE.WebGPURenderer(props as any); await r.init(); return r }} />

When to Use What

Scene Setup Patterns

tsxCopy code
import { Canvas } from '@react-three/fiber'
import { Environment, OrbitControls } from '@react-three/drei'
import { Suspense } from 'react'

<Canvas camera={{ position: [0, 2, 5], fov: 45 }} dpr={[1, 2]} gl={{ antialias: true }}>
  <Suspense fallback={null}>
    <Environment preset="studio" />
    <OrbitControls makeDefault />
    <Scene />
  </Suspense>
</Canvas>

Rules:

• Always wrap scene content in <Suspense> -- loaders (GLTF, textures, HDRI) need it
• Set dpr={[1, 2]} to clamp pixel ratio (Retina without melting GPUs)
• Keep the Canvas parent component minimal -- re-renders propagate into the scene

R3F Hooks

useFrame Tips

tsxCopy code
useFrame((state, delta) => {
  // Use delta for framerate-independent animation
  meshRef.current.rotation.y += delta * 0.5
  // Access clock for time-based effects
  material.uniforms.uTime.value = state.clock.elapsedTime
})

Drei Essentials

Postprocessing

tsxCopy code
import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

<EffectComposer>
  <Bloom
    luminanceThreshold={1}
    luminanceSmoothing={0.4}
    intensity={0.6}
  />
  <ChromaticAberration
    blendFunction={BlendFunction.NORMAL}
    offset={[0.002, 0.002]}
  />
</EffectComposer>

Rules:

• Bloom is selective by default -- lift material color/emissive above 1.0 to make it glow
• luminanceThreshold={1} = nothing glows unless explicitly emissive
• Order matters inside EffectComposer
• Effects are merged into a single pass (performant by design)

Performance Patterns

Target metrics: < 100 draw calls, < 1M triangles, 60fps on mid-range GPU. Use stats-gl or r3f-perf to monitor.

Do Not

1. Never setState in useFrame

Causes full React re-render 60x/second. Mutate refs directly.

tsxCopy code
// BAD
useFrame(() => {
  setRotation(prev => prev + 0.01) // React re-render every frame
})

// GOOD
useFrame((_, delta) => {
  meshRef.current.rotation.y += delta * 0.5 // Direct mutation, zero re-renders
})

2. Never allocate in the render loop

new Vector3() per frame = GC spikes = stutter.

tsxCopy code
// BAD
useFrame((state) => {
  const target = new THREE.Vector3(0, Math.sin(state.clock.elapsedTime), 0)
  meshRef.current.position.copy(target)
})

// GOOD
const _target = useMemo(() => new THREE.Vector3(), [])
useFrame((state) => {
  _target.set(0, Math.sin(state.clock.elapsedTime), 0)
  meshRef.current.position.copy(_target)
})

3. Never forget dispose (memory leak)

Three.js textures, geometries, and materials live on the GPU. Unmounting a React component does NOT free them.

tsxCopy code
// BAD -- texture stays in VRAM after unmount
const texture = useLoader(TextureLoader, '/big-texture.jpg')

// GOOD -- R3F auto-disposes when using JSX primitives
// For manual resources, dispose in cleanup:
useEffect(() => {
  return () => {
    texture.dispose()
    geometry.dispose()
    material.dispose()
  }
}, [])

4. Never re-render the Canvas parent

State changes in the parent force the entire Canvas to remount = flash, lost state, reloaded assets.

tsxCopy code
// BAD
function App() {
  const [uiState, setUiState] = useState(false) // re-renders remount Canvas
  return (
    <>
      <button onClick={() => setUiState(!uiState)}>Toggle</button>
      <Canvas><Scene config={uiState} /></Canvas>
    </>
  )
}

// GOOD -- isolate Canvas in its own component
function App() {
  return (
    <>
      <UI />
      <SceneCanvas />
    </>
  )
}

5. Never load assets without Suspense

Loaders (useGLTF, useTexture, useLoader) throw promises. Without Suspense, you get crashes.

tsxCopy code
// BAD
<Canvas>
  <Model /> {/* useGLTF inside -- will throw */}
</Canvas>

// GOOD
<Canvas>
  <Suspense fallback={<Loader />}>
    <Model />
  </Suspense>
</Canvas>

Quick Reference: Loading Sub-resources