zebbern/claude-code-guide / skills/r3f-best-practices
r3f-best-practices
VerifiedReact Three Fiber (R3F) and Poimandres ecosystem best practices. Use when writing, reviewing, or optimizing R3F code. Triggers on tasks involving @react-three/fiber, @react-three/drei, zustand, @react-three/postprocessing, @react-three/rapier, or leva.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
| rules/_sections.md | markdown | 1.9 KB |
| rules/drei-use-gltf.md | markdown | 3.0 KB |
| rules/frame-delta-time.md | markdown | 2.7 KB |
| rules/loading-suspense.md | markdown | 3.6 KB |
| rules/perf-never-set-state-in-useframe.md | markdown | 2.6 KB |
| rules/perf-r3f-perf.md | markdown | 1.9 KB |
| rules/perf-visibility-toggle.md | markdown | 1.9 KB |
| rules/perf-zustand-selectors.md | markdown | 3.0 KB |
rules/perf-never-set-state-in-useframe.md
View on GitHub# perf-never-set-state-in-useframe
**NEVER call setState inside useFrame.**
## Why It Matters
This is the #1 performance killer in R3F. Calling setState triggers React re-renders. useFrame runs at 60fps. setState in useFrame = 60 re-renders per second = destroyed performance.
## Bad Example
```jsx
// BAD - Causes 60 re-renders per second!
function BadComponent() {
const [position, setPosition] = useState(0);
useFrame(() => {
setPosition(p => p + 0.01); // NEVER DO THIS
});
return <mesh position-x={position} />;
}
```
This triggers React reconciliation 60 times per second, causing:
- Massive CPU usage
- Frame drops
- Component re-creation
- Garbage collection pauses
## Good Example
```jsx
// GOOD - Mutate refs directly, no re-renders
function GoodComponent() {
const meshRef = useRef();
useFrame(() => {
meshRef.current.position.x += 0.01;
});
return <mesh ref={meshRef} />;
}
```
The ref gives direct access to the Three.js object. Mutating it doesn't trigger React.
## With Delta Time
```jsx
function AnimatedComponent() {
const meshRef = useRef();
useFrame((state, delta) => {
meshRef.current.rotation.y += 1 * delta; // 1 rad/sec
meshRef.current.position.x = Math.sin(state.clock.elapsedTime);
});
return <mesh ref={meshRef} />;
}
```
## Multiple Values
```jsx
function ComplexAnimation() {
const meshRef = useRef();
useFrame(({ clock }) => {
const t = clock.elapsedTime;
meshRef.current.position.set(
Math.sin(t) * 2,
Math.cos(t * 2),
Math.sin(t * 0.5)
);
meshRef.current.rotation.set(t, t * 0.5, 0);
});
return <mesh ref={meshRef} />;
}
```
## Using Zustand Without Re-renders
```jsx
function ZustandAnimation() {
const meshRef = useRef();
useFrame(() => {
// getState() doesn't trigger re-renders
const { targetPosition } = useStore.getState();
meshRef.current.position.lerp(targetPosition, 0.1);
});
return <mesh ref={meshRef} />;
}
```
## When You NEED State
If you genuinely need React state (e.g., for UI updates), isolate it:
```jsx
// Keep animated mesh separate
function AnimatedMesh() {
const meshRef = useRef();
useFrame((_, delta) => {
meshRef.current.rotation.y += delta;
});
return <mesh ref={meshRef} />;
}
// State changes here won't affect AnimatedMesh
function UI() {
const [score, setScore] = useState(0);
return <Html><div>{score}</div></Html>;
}
function Scene() {
return (
<>
<AnimatedMesh />
<UI />
</>
);
}
```
## References
- [R3F Performance Pitfalls](https://docs.pmnd.rs/react-three-fiber/advanced/pitfalls)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |