perf-r3f-perf — Claude Code rule: React Three Fiber monitoring
The perf-r3f-perf rule teaches Claude Code about r3f-perf, a performance monitoring library for Three.js scenes in real time. Spot frame drops, memory leaks, and unnecessary matrix recalculations as they happen.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/perf-r3f-perf.mdWhat perf-r3f-perf does
r3f-perf displays FPS, frame time (milliseconds), CPU and GPU load, memory usage, and draw call count directly on screen. Enable deep analysis to profile render time per object, though it adds overhead. The component positions itself in any corner, supports minimal mode (FPS only), and can render a live performance graph.
The rule shows Claude Code how to add <Perf /> to Canvas, adjust its props, and conditionally disable it in production via process.env.NODE_ENV === 'development'. The monitor itself consumes resources—disable or minimize it before shipping.
What it helps with
- spot frame rate drops in Three.js scenes
- detect geometry and texture memory leaks
- count draw calls and optimize rendering batches
- profile render time for individual objects
Example prompts for the agent
- Add r3f-perf to Canvas to see live FPS and frame timing
- Position the monitor and enable the performance graph for visual feedback
- Turn on deepAnalyze to find which object consumes the most render time
How to install perf-r3f-perf
Manually: put the files in place
.claude/rules/perf-r3f-perf.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-r3f-perf.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/perf-r3f-perf.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/perf-r3f-perf.mdManually: put the files in place
.clinerules/perf-r3f-perf.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about perf-r3f-perf
How do I install perf-r3f-perf in Claude Code?
Create .claude/rules/perf-r3f-perf.md with the rule content. Claude Code loads it automatically on the next project start.
What does r3f-perf monitor?
Frames per second, milliseconds per frame, JavaScript execution time, WebGL draw time, memory for geometries and textures, and matrix recalculation count. All output appears on screen during development.
When should I use deepAnalyze mode?
Only when hunting for a specific bottleneck. The mode increases CPU cost, so enable it briefly—deep analysis itself can skew measurements and slow things down.
Source text
perf-r3f-perf.md · MIT
# r3f-perf for Performance Monitoring
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Use r3f-perf for comprehensive React Three Fiber performance monitoring.
## Installation
```bash
npm install r3f-perf
```
## Basic Usage
```jsx
import { Perf } from 'r3f-perf';
function App() {
return (
<Canvas>
<Perf position="top-left" />
<Scene />
</Canvas>
);
}
```
## Available Props
```jsx
<Perf
position="top-left" // Position: top-left, top-right, bottom-left, bottom-right
minimal={false} // Minimal mode (just FPS)
showGraph={true} // Show performance graph
matrixUpdate={true} // Show matrix updates
deepAnalyze={false} // Deep analysis (more CPU intensive)
overClock={false} // Over-clock mode for high refresh rate monitors
logsPerSecond={10} // Logs per second
/>
```
## What It Monitors
- **FPS** - Frames per second
- **MS** - Milliseconds per frame
- **CPU** - JavaScript execution time
- **GPU** - WebGL draw time (estimated)
- **Memory** - Geometries, textures, draw calls
- **Matrix Updates** - Number of matrix recalculations
## Conditional Rendering for Production
```jsx
import { Perf } from 'r3f-perf';
function App() {
const isDev = process.env.NODE_ENV === 'development';
return (
<Canvas>
{isDev && <Perf position="top-left" />}
<Scene />
</Canvas>
);
}
```
## Deep Analyze Mode
For detailed per-object analysis:
```jsx
<Perf
deepAnalyze={true}
className="custom-perf"
/>
```
Shows render times for individual objects but has higher CPU overhead.
## Best Practices
1. **Remove in production** - Always hide in production builds
2. **Use sparingly** - Performance monitor itself has overhead
3. **Check draw calls** - Target under 100 draw calls
4. **Monitor memory** - Watch for leaking geometries/textures
5. **Use alongside renderer.info** - For detailed WebGL stats
© zebbern · MIT · zebbern/claude-code-guide