Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/perf-never-set-state-in-useframe.md
Open on GitHub

What 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 setState calls hidden inside useFrame callbacks
  • 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.jsx for setState inside useFrame and rewrite it to mutate the mesh ref.
  • The animation stutters. Look at whether component state updates on every frame.
  • Move the rotation onto delta and 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
official-docs-researcher The official-docs-researcher subagent checks official sources when a decision hinges on a current API, release, schema, model, or version-specific behavior. CX Codex ★ 4,719repo stars change-implementer change-implementer — a subagent that carries one pre-approved change through to the end: edits the code, runs it for real, and reports what it observed. CX Codex ★ 4,719repo stars tsl-why-use tsl-why-use — a rule that pushes the coding agent to build custom Three.js materials from TSL nodes rather than patching shaders through onBeforeCompile. CX Codex +1 ★ 4,719repo stars asset-compression Guides your AI coding agent through 3D asset compression for Three.js. Covers Draco, Meshopt, KTX2 textures, and LOD implementation. CX Codex +1 ★ 4,719repo stars frame-delta-time frame-delta-time — a rule that makes every animated movement multiply by delta, so speed stops depending on the display's refresh rate. CX Codex +1 ★ 4,719repo stars draw-call-optimization The draw-call-optimization rule for Claude Code guides Three.js optimization, reducing draw calls to below 100 per frame through instancing, batching, and geometry merging. CX Codex +1 ★ 4,719repo stars object-pooling object-pooling — a rule that pushes the agent to reuse bullets, particles and NPCs from a pool instead of building and discarding meshes every frame. CX Codex +1 ★ 4,719repo stars shader-mobile The shader-mobile rule for Claude Code provides guidelines for optimizing GLSL and Three.js shaders for mobile GPUs to prevent framerate drops on mobile devices. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open