SuperAPI AI Directory

r3f

General & other

View repository

Updated 10-16 06:14

About this skill

React Three Fiber v9 + drei v10

Declarative 3D scenes in React. Complements the skill threejs (imperative vanilla Three.js).

Mental Model

React and Three.js handle distinct domains that communicate via refs:

  • React owns the scene graph: mounts, unmounts, reconciles JSX components → Three.js objects
  • Three.js owns the render loop: useFrame runs every frame, mutates refs directly
  • Golden rule: React for state and structure, refs for per-frame mutations
React tree (JSX, state, props)
      ↕ refs / props
useFrame callbacks (per-frame mutations)
      ↕ escribe en Three.js objects
WebGLRenderer (render en priority 0)

When to Use This Skill vs threejs

Scenario Skill
React + JSX project for 3D r3f (this one)
Imperative vanilla Three.js threejs
Concepts of materials, lights, shadows threejs (apply the same)
Hooks: useFrame, useThree, useLoader r3f
drei helpers: controls, staging, text r3f
CSG with @react-three/csg r3f

Quick Start

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

function Box() {
  return (
    <mesh castShadow>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="orange" roughness={0.4} />
    </mesh>
  )
}

export function Scene() {
  return (
    <Canvas shadows camera={{ position: [3, 3, 3], fov: 50 }}>
      <ambientLight intensity={0.4} />
      <directionalLight position={[5, 5, 5]} castShadow />
      <Box />
      <OrbitControls makeDefault />
      <Environment preset="studio" />
    </Canvas>
  )
}

Learning Path

Level 1: Core R3F

  • Canvas and Hooks: references/01-canvas-hooks.md — Canvas props, useThree, useFrame, useLoader, useGraph
  • JSX and Events: references/02-jsx-system.md — JSX→Three.js mapping, args, attach, extend, primitive, events

Level 2: drei Ecosystem

  • Controls: references/03-drei-controls.md — OrbitControls, CameraControls, PivotControls, TransformControls, Keyboard/Scroll
  • Staging: references/04-drei-staging.md — Environment, shadows, Sky, special materials
  • Abstractions: references/05-drei-abstractions.md — Text, Html, Billboard, Image, Clone, loaders, animations

Level 3: Performance and Patterns

  • Performance: references/06-drei-performance.md — Bvh, Instances, LOD, PerformanceMonitor, dispose, FBO
  • Zustand Bridge: references/07-zustand-integration.md — getState() in useFrame, invalidate(), demand rendering

Level 4: Specialized

  • CSG Operations: references/08-csg-operations.md — @react-three/csg, three-bvh-csg, boolean geometry
  • TypeScript v9: references/09-typescript-v9.md — ThreeElements, ThreeElement, module augmentation, migration
  • Patterns and Gotchas: references/10-patterns-gotchas.md — anti-patterns, disposal, Suspense, portals

10 Core Rules

  1. Never setState in useFrame — causes re-render at 60fps. Use refs or useStore.getState()
  2. useThree with selector — useThree(s => s.camera), not useThree() bare (re-render on every state change)
  3. extend() mandatory for custom objects — v9 does not auto-discover. extend({ MyClass }) before the JSX
  4. Suspense boundary around loaders — useGLTF, useTexture, useLoader suspend the component
  5. frameloop="demand" for static scenes — invalidate() from useThree or store to trigger frames
  6. args as constant — args={[1,1,1]} inline recreates every render. Hoist or useMemo
  7. dispose={null} for shared resources — R3F auto-disposes on unmount; prevent with dispose={null}
  8. makeDefault on controls — registers in state.controls so drei components can access it
  9. primitive does not clone — <primitive object={obj}/> uses the same reference. Use <Clone> from drei to reuse
  10. Events only on meshes with geometry — onClick in <group> without geometry does not fire

Anti-Patterns

Anti-pattern Problem Fix
setState(x) in useFrame Re-renders 60fps Refs or Zustand getState()
useThree() without selector Re-render on any change useThree(s => s.camera)
new THREE.Vector3() in render GC pressure per-frame Hoist or useMemo
args={[w,h,d]} inline Rebuilds geometry every render useMemo(() => [w,h,d], [w,h,d])
1000 <mesh> individual Slow reconciliation <Instances> from drei
useEffect to animate Outside the render loop useFrame with refs

Pre-Deploy Checklist

[ ] frameloop="demand" si la escena no se anima constantemente
[ ] <Suspense> alrededor de componentes con loaders
[ ] dispose={null} en <primitive> de recursos compartidos
[ ] <Bvh> wrapper si hay muchos meshes clickeables
[ ] dpr={[1, 2]} en Canvas para DPR adaptativo
[ ] OrbitControls con makeDefault
[ ] Sin setState en ningun useFrame
[ ] gl={{ preserveDrawingBuffer: true }} solo si necesitas screenshots

Resources