React Three Fiber Application Architecture

What this builds

The architectural skeleton of a production R3F application: where state lives (React vs Zustand vs refs), how 3D components communicate without triggering re-renders, how assets load with Suspense boundaries, how the render loop is managed (always vs demand), and how everything cleans up on unmount. This is the decision framework that separates a 60fps production app from a demo that stutters when you add a second model.

• Clear state boundary: React state for UI, Zustand store for 3D scene state, refs for per-frame mutation.
• Suspense-based asset loading with preloading, error boundaries, and loading UI.
• Demand-mode rendering for static/interactive scenes that do not need continuous animation.
• Component patterns: scene composition, forwarded refs, imperative handles, instanced batches.
• Full disposal on unmount: useEffect cleanup, useGLTF cache invalidation, texture cleanup.
• Performance patterns: useMemo for geometry/materials, useFrame subscription ordering, avoiding re-renders.

When to use / when not to

• Use when building any R3F project beyond a single-file demo. The architecture decisions here prevent the performance problems you hit at the 3rd or 4th component.
• Use when the project has both 3D content and significant React UI (modals, controls, data panels) that need to coexist without tanking frame rate.
• Use when multiple developers will work on the same R3F codebase and need conventions about where state goes.
• Do NOT use for vanilla Three.js projects (no React). Use three-scene-architecture-framework instead.
• Do NOT use when you need detailed R3F/drei API reference. See react-three-fiber-drei for the API surface; this toolkit is about how to structure the app around that API.
• Do NOT use for a fullscreen shader background in React. A raw <canvas> with WebGL2 is lighter. See hero-webgl-shader-fullscreen.