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/loading-suspense.md
View on GitHub# loading-suspense
**Wrap async components in Suspense.**
## Why It Matters
R3F integrates with React Suspense for loading states. Components using `useGLTF`, `useTexture`, or other async loaders will suspend and need a Suspense boundary with a fallback.
## Basic Example
```jsx
import { Suspense } from 'react';
import { Canvas } from '@react-three/fiber';
import { useGLTF } from '@react-three/drei';
function Model() {
const { scene } = useGLTF('/model.glb');
return <primitive object={scene} />;
}
function App() {
return (
<Canvas>
<Suspense fallback={<LoadingFallback />}>
<Model />
</Suspense>
</Canvas>
);
}
function LoadingFallback() {
return (
<mesh>
<boxGeometry />
<meshBasicMaterial wireframe color="white" />
</mesh>
);
}
```
## Multiple Async Components
```jsx
function Scene() {
return (
<Suspense fallback={<Loader />}>
<Environment preset="city" />
<Model url="/character.glb" />
<Ground />
</Suspense>
);
}
```
## Nested Suspense Boundaries
```jsx
function Scene() {
return (
<>
{/* Environment loads first */}
<Suspense fallback={null}>
<Environment preset="sunset" />
</Suspense>
{/* Main content with visible loader */}
<Suspense fallback={<Loader />}>
<Character />
<Props />
</Suspense>
{/* Background loads last, no blocking */}
<Suspense fallback={null}>
<BackgroundDetails />
</Suspense>
</>
);
}
```
## Using useProgress
```jsx
import { useProgress, Html } from '@react-three/drei';
function Loader() {
const { active, progress, errors, item, loaded, total } = useProgress();
return (
<Html center>
<div className="loader">
<div className="progress-bar">
<div
className="progress-fill"
style={{ width: `${progress}%` }}
/>
</div>
<p>{progress.toFixed(0)}% loaded</p>
<p className="loading-item">{item}</p>
</div>
</Html>
);
}
function App() {
return (
<Canvas>
<Suspense fallback={<Loader />}>
<Scene />
</Suspense>
</Canvas>
);
}
```
## Error Boundaries
```jsx
import { ErrorBoundary } from 'react-error-boundary';
function ModelErrorFallback({ error, resetErrorBoundary }) {
return (
<Html center>
<div>
<p>Failed to load model</p>
<button onClick={resetErrorBoundary}>Try again</button>
</div>
</Html>
);
}
function SafeModel({ url }) {
return (
<ErrorBoundary
FallbackComponent={ModelErrorFallback}
onReset={() => {
// Reset any state if needed
}}
>
<Suspense fallback={<LoadingBox />}>
<Model url={url} />
</Suspense>
</ErrorBoundary>
);
}
```
## Preloading to Avoid Suspense
```jsx
import { useGLTF, useTexture } from '@react-three/drei';
// Preload at module level
useGLTF.preload('/model.glb');
useTexture.preload('/texture.png');
// Component won't suspend if already loaded
function Model() {
const { scene } = useGLTF('/model.glb'); // Instant if preloaded
return <primitive object={scene} />;
}
```
## Animated Fallback
```jsx
function AnimatedLoader() {
const meshRef = useRef();
useFrame((state) => {
meshRef.current.rotation.x = state.clock.elapsedTime;
meshRef.current.rotation.y = state.clock.elapsedTime * 0.5;
});
return (
<mesh ref={meshRef}>
<icosahedronGeometry args={[1, 1]} />
<meshBasicMaterial wireframe color="cyan" />
</mesh>
);
}
```
## References
- [React Suspense](https://react.dev/reference/react/Suspense)
- [Drei useProgress](https://github.com/pmndrs/drei#useprogress)
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 |