Core concepts

Canvas

The root component that creates a renderer, scene, and camera. Past R3F versions exposed the WebGL renderer via state.gl; newer versions (v10 alpha) rename this to state.renderer and add first-class WebGPU support. R3F lets you provide a gl prop to Canvas — it can be a renderer constructor, a renderer instance, or an async callback that returns a renderer (required for WebGPU's async initialization).

Basic WebGL example:

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

<Canvas camera={{ position: [0, 2, 5], fov: 50 }}>
  <ambientLight intensity={0.5} />
  <directionalLight position={[10, 10, 5]} intensity={1} />
  <mesh>
    <boxGeometry args={[1, 1, 1]} />
    <meshStandardMaterial color="hotpink" />
  </mesh>
</Canvas>

Async WebGPU initialization pattern (supported via async gl prop):

import * as THREE from 'three/webgpu';
import { Canvas } from '@react-three/fiber';

<Canvas
  gl={async (props) => {
    const renderer = new THREE.WebGPURenderer(props as any);
    await renderer.init(); // WebGPU renderer needs async init
    return renderer;
  }}
>
  {/* scene */}
</Canvas>

(See the R3F docs and release notes for migration examples and details.)

useFrame (per-frame updates)

useFrame remains the mechanism for per-frame updates. The core guidance stands — avoid calling React setState every frame; mutate refs instead. Newer R3F versions introduce an improved scheduler that gives useFrame advanced scheduling options and the ability to register frame callbacks outside of <Canvas /> (use cases: render orchestration, headless loops). If you rely on scheduler-specific behavior, consult the release notes for the scheduler API and options.

Example (still prefer refs for per-frame mutation):

import { useFrame } from '@react-three/fiber';
import { useRef } from 'react';

function SpinningBox() {
  const meshRef = useRef(null);
  useFrame((_, delta) => {
    if (meshRef.current) meshRef.current.rotation.y += delta * 0.5;
  });
  return (
    <mesh ref={meshRef}>
      <boxGeometry />
      <meshStandardMaterial color="orange" />
    </mesh>
  );
}

Model loading with useGLTF / useLoader

Drei continues to supply helpers like useGLTF. Best practice remains: wrap loads in <Suspense> and call useGLTF.preload() for assets you want downloaded early. From R3F v9 onward, useLoader accepts loader instances (useful for pooling or custom loader configuration).

import { useGLTF } from '@react-three/drei';

function Model({ url }: { url: string }) {
  const { scene } = useGLTF(url);
  return <primitive object={scene} />;
}

useGLTF.preload('/models/product.glb');

Environment, lighting, and drei helpers

Drei remains the recommended source for ready-made helpers: Environment, ContactShadows, OrbitControls, Text, Float, Instances, etc. Drei v11 (alpha) introduces helper updates and WebGPU-ready helpers; pin or test helper versions when upgrading. Use Environment for IBL reflections and ContactShadows for soft ground shadows.

Post-processing

Post-processing libraries integrated with R3F (for example @react-three/postprocessing and newer WebGPU-capable pipelines) still use an effect composer pattern. For WebGPU there are evolving hooks and helpers (R3F v10 alpha includes WebGPU-specific hooks such as useUniforms, useNodes, useLocalNodes, and usePostProcessing designed to work with the new renderer) — test post-processing pipelines when changing the renderer backend.

Example (postprocessing with existing GL):

import { EffectComposer, Bloom, Vignette } from '@react-three/postprocessing';

<EffectComposer>
  <Bloom luminanceThreshold={0.9} intensity={0.5} />
  <Vignette offset={0.3} darkness={0.5} />
</EffectComposer>

Workflow

1. Set up the Canvas
   • Use camera, dpr, and gl options. If you intend to try WebGPU, provide an async gl initializer (see example above).
2. Add lighting and environment
   • Use Environment for reflections and directionalLight for shadows. Drei helpers simplify realistic setups.
3. Load models
   • Use useGLTF or useLoader. Wrap loads with <Suspense> and show a fallback UI. Preload heavy assets.
4. Add interaction
   • Use R3F pointer events and drei interaction helpers. Avoid frequent React re-renders inside pointer handlers used in animation loops.
5. Profile performance
   • Use r3f-perf (development only) or Chrome DevTools to monitor draw calls, memory, and frame times. Profile both WebGL and WebGPU backends if you support multiple renderers.
6. Provide fallbacks for SSR and slow connections
   • R3F renders on the client. Use dynamic imports with ssr: false (Next.js) and provide a static poster/snapshot while the canvas loads.

Compatibility & migration (concrete guidance)

• R3F v10 (alpha) — WebGPU, scheduler, and API changes

  • The v10 alpha introduces WebGPU support and a new scheduler. state.gl is renamed to state.renderer — update custom code that referenced state.gl accordingly. (See pmndrs/react-three-fiber releases: v10.0.0-alpha.1.)
  • WebGPU requires async initialization; R3F supports returning a promise from the gl prop to produce an async renderer instance. See R3F migration docs for an example of async gl and WebGPURenderer initialization.
  • R3F adds WebGPU-specific hooks (e.g. useUniforms, useNodes, useLocalNodes, usePostProcessing) designed to work with TSL/WebGPU workflows.

• Drei v11 (alpha)

  • Drei is being updated alongside R3F to provide helper compatibility and WebGPU-ready components. Test helpers after upgrading and pin working helper versions in production.

• React compatibility and security

  • R3F is client-only. If you use React Server Components (RSC) or server bundles, do not attempt to render R3F on the server — keep 3D code in client components (dynamic import with ssr: false).
  • There have been recent security advisories affecting React Server Components; keep React upgraded to the patched versions and follow React security guidance. (See React Blog advisories on RSC vulnerabilities and the React v19 release notes for upgrades.)

• useLoader and loader instances (v9+)

  • useLoader accepts loader instances now, enabling reuse/pooling of loaders for memory/control.

Examples (updated)

• WebGL Canvas (unchanged — same API surface)
• WebGPU Canvas (async gl example shown earlier)
• useLoader with loader instance

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
import { useLoader } from '@react-three/fiber';

const loader = new GLTFLoader();
function Model() {
  const gltf = useLoader(loader, '/models/model.glb');
  return <primitive object={gltf.scene} />;
}

Edge cases and gotchas (updates)

1. Never setState in useFrame — this triggers React re-renders every frame. Use refs for animation state.
2. Memory and resource disposal
   • WebGL and WebGPU resources must be disposed when no longer needed. WebGPU brings new resource types; ensure any custom WebGPU allocations are cleaned up. Drei and useGLTF help with cleanup but test carefully after upgrades.
3. SSR mismatch
   • R3F uses WebGL/WebGPU, which do not exist on the server. Use dynamic imports with ssr: false and provide a static poster while the client hydrates.
4. Large models and compression
   • GLB files over a few megabytes slow page loads. Use gltf-transform, Draco, or mesh quantization. Show a progress indicator during large downloads.
5. DPR and mobile performance
   • Cap device pixel ratio for mobile devices: dpr={[1, 1.5]} or similar to reduce GPU load.
6. WebGPU caveats
   • WebGPU support in three.js and browsers is progressing but not yet feature-parity with WebGL. Expect API changes and differences in post-processing and shader libraries. Test both backends if you ship them.
7. Z-fighting
   • Offset nearly-coplanar surfaces or use polygonOffset.

Performance checklist (updated)

• useFrame never calls setState — use refs for per-frame updates
• All geometries, materials, and textures are disposed on unmount
• Models are wrapped in <Suspense> with a loading fallback
• Models are preloaded with useGLTF.preload() when appropriate
• SSR is handled via dynamic import with ssr: false
• Performance is profiled with r3f-perf during development
• Instanced meshes or Instances from drei are used for repeated geometry
• DPR is capped appropriately for target devices
• Code referencing renderer uses state.renderer (or updated API) if using R3F v10+; gl may be provided asynchronously for WebGPU

Decision tree (short)

• 3D product viewer in React? → @react-three/fiber + useGLTF + OrbitControls
• Atmospheric hero scene? → R3F + Environment + post-processing
• Many identical objects? → Instances from drei or GPU instancing
• Animated 3D object? → useFrame with ref mutation (not setState)
• Need SSR? → Keep 3D client-only; use dynamic import with ssr: false

Links & references

• pmndrs/react-three-fiber releases (v10 alpha — WebGPU, scheduler, state.renderer) — https://github.com/pmndrs/react-three-fiber/releases
• pmndrs/drei releases (v11 alpha) — https://github.com/pmndrs/drei/releases
• R3F v9 migration guide (async gl prop, WebGPU example) — https://r3f.docs.pmnd.rs/tutorials/v9-migration-guide
• React Blog — React v19 and RSC security advisories (see React blog posts and release notes)

(Keep pinned versions in production and test upgrades in a branch. When adopting WebGPU, treat it as an experimental backend until your testing confirms parity with your WebGL setup.)