perf-never-set-state-in-useframe — Claude Code rule: what it does
perf-never-set-state-in-useframe — a react-three-fiber rule that bans setState inside useFrame and pushes you to mutate a ref instead, so animation stops triggering a React render every frame.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/perf-never-set-state-in-useframe.mdWhat perf-never-set-state-in-useframe does
useFrame runs on every rendered frame. A setState call inside it schedules a React update just as often, and the tree gets reconciled at frame rate. The rule states the fix plainly: write to ref.current on the Three.js object rather than holding the value in component state, since a mutation never reaches React.
The file is example-driven. A bad version keeps position in state, a good one mutates a mesh ref, and a delta variant makes rotation speed independent of frame rate. Several axes at once go through position.set and rotation.set. With Zustand, reading the store via getState() skips the subscription, so a target can be pulled inside useFrame and eased with lerp.
React state still has a place for UI. Keep the animated mesh in its own component and put the score or label in a sibling, so a state change there doesn't reach the mesh. Any useFrame callback that calls setState is the thing to grep for.
What it helps with
- catch
setStatecalls hidden insideuseFramecallbacks - move per-frame animation from React state onto a mesh ref
- decouple rotation speed from frame rate with
delta - read a Zustand target without subscribing the component
- keep UI state out of the animated mesh
Example prompts for the agent
- Check
Scene.jsxforsetStateinsideuseFrameand rewrite it to mutate the mesh ref. - The animation stutters. Look at whether component state updates on every frame.
- Move the rotation onto
deltaand leave state only for the score in the UI.
How to install perf-never-set-state-in-useframe
Manually: put the files in place
.claude/rules/perf-never-set-state-in-useframe.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/perf-never-set-state-in-useframe.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/perf-never-set-state-in-useframe.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/perf-never-set-state-in-useframe.mdManually: put the files in place
.clinerules/perf-never-set-state-in-useframe.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about perf-never-set-state-in-useframe
How do I install perf-never-set-state-in-useframe in Claude Code?
Place the rule file in your project at .claude/rules/perf-never-set-state-in-useframe.md.
What does perf-never-set-state-in-useframe do?
It forbids setState inside useFrame in react-three-fiber and points to mutating ref.current as the replacement.
Why does setState inside useFrame hurt frame rate?
useFrame fires at frame rate, so every call queues another render. The component tree ends up reconciling constantly, which shows up as dropped frames and garbage collection pauses.
Source text
perf-never-set-state-in-useframe.md · MIT
# 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)
© zebbern · MIT · zebbern/claude-code-guide