perf-never-set-state-in-useframe — правило R3F
Правило perf-never-set-state-in-useframe для react-three-fiber: не вызывать setState внутри useFrame, потому что это даёт перерисовку на каждом кадре. Вместо состояния React — мутация ref.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/perf-never-set-state-in-useframe.mdЧто делает perf-never-set-state-in-useframe
useFrame из react-three-fiber срабатывает на каждом кадре. Если внутри стоит setState, React пересобирает компонент с той же частотой, и почти всё время кадра уходит на это. Правило требует другого: держать объект Three.js в ref и менять ref.current.position напрямую. Такой мутации React не видит и перерисовку не запускает.
Внутри разобраны два примера, плохой и хороший, плюс вариант с delta: поворот задаётся в радианах в секунду и не зависит от частоты кадров. Несколько осей сразу ставятся через position.set и rotation.set. Для Zustand есть отдельный случай: чтение через getState() не подписывает компонент, поэтому цель можно брать прямо в useFrame и подтягивать через lerp.
Состояние React всё ещё нужно для интерфейса. Анимированный меш выносят в отдельный компонент, а счёт или подпись держат рядом в обычном: обновление счёта тогда не трогает меш. Искать по проекту стоит любой useFrame с setState внутри, потому что именно такой вызов и роняет кадры.
Какие задачи решает
- найти
setStateвнутриuseFrameи убрать лишние перерисовки - перевести покадровую анимацию с состояния React на мутацию
ref - сделать скорость поворота независимой от частоты кадров через
delta - читать цель из Zustand без подписки компонента на стор
- вынести состояние интерфейса из анимированного компонента
Примеры запросов агенту
- Проверь
Scene.jsx: если внутриuseFrameвызываетсяsetState, перепиши на мутациюref. - Анимация дёргается. Посмотри, не обновляется ли состояние компонента на каждом кадре.
- Переведи вращение на
delta, а состояние оставь только для счёта в интерфейсе.
Как установить perf-never-set-state-in-useframe
Вручную: положить файлы
.claude/rules/perf-never-set-state-in-useframe.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/perf-never-set-state-in-useframe.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/perf-never-set-state-in-useframe.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/perf-never-set-state-in-useframe.mdВручную: положить файлы
.clinerules/perf-never-set-state-in-useframe.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о perf-never-set-state-in-useframe
Как установить perf-never-set-state-in-useframe в Claude Code?
Положите файл правила в проект по пути .claude/rules/perf-never-set-state-in-useframe.md.
Что делает perf-never-set-state-in-useframe?
Запрещает вызывать setState внутри useFrame в react-three-fiber и показывает замену: правку ref.current у объекта Three.js.
Почему setState в useFrame так бьёт по кадрам?
useFrame идёт с частотой кадров, и каждый вызов setState планирует новую пересборку дерева React. Отсюда просадки кадров и паузы сборки мусора.
Исходный текст
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