zebbern/claude-code-guide / skills/three-best-practices
three-best-practices
VerifiedThree.js performance optimization and best practices guidelines. Use when writing, reviewing, or optimizing Three.js code. Triggers on tasks involving 3D scenes, WebGL/WebGPU rendering, geometries, materials, textures, lighting, shaders, or TSL.
rules/core-web-vitals.md
View on GitHub# Core Web Vitals & Loading
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Optimize loading performance to improve LCP, FID, and CLS scores.
## Lazy Load 3D Content Below the Fold
Don't block page load with 3D content that's not visible.
```javascript
const observer = new IntersectionObserver((entries) => {
if (entries[0].isIntersecting) {
loadThreeJsScene();
observer.disconnect();
}
});
observer.observe(canvasContainer);
```
## Code-Split Three.js Modules
Dynamic imports reduce initial bundle size.
```javascript
// Load Three.js only when needed
const Three = await import('three');
const { GLTFLoader } = await import('three/addons/loaders/GLTFLoader.js');
```
## Preload Critical Assets
Use `<link rel="preload">` for critical resources:
```html
<link rel="preload" href="/model.glb" as="fetch" crossorigin>
<link rel="preload" href="/texture.ktx2" as="fetch" crossorigin>
```
## Progressive Loading
Show low-res content immediately, upgrade when ready:
```javascript
// Show low-res immediately
const lowRes = await loadModel('low.glb');
scene.add(lowRes);
// Load and swap high-res in background
loadModel('high.glb').then(highRes => {
scene.remove(lowRes);
lowRes.traverse(child => {
if (child.geometry) child.geometry.dispose();
if (child.material) child.material.dispose();
});
scene.add(highRes);
});
```
## Placeholder Geometry
Show loading state with placeholder geometry:
```javascript
const placeholder = new THREE.Mesh(
new THREE.BoxGeometry(1, 1, 1),
new THREE.MeshBasicMaterial({ color: 0x808080, wireframe: true })
);
scene.add(placeholder);
loadModel().then(model => {
scene.remove(placeholder);
placeholder.geometry.dispose();
placeholder.material.dispose();
scene.add(model);
});
```
## Offload to Web Workers
Move CPU-intensive work off main thread:
```javascript
// main.js
const worker = new Worker('/physics-worker.js');
worker.postMessage({ positions, velocities });
worker.onmessage = (event) => {
updatePositions(event.data.positions);
};
// physics-worker.js
self.onmessage = (event) => {
const result = computePhysics(event.data);
self.postMessage(result);
};
```
## Stream Large Scenes
Load chunks based on camera position:
```javascript
function updateVisibleChunks(cameraPosition) {
const visibleChunks = getChunksNear(cameraPosition);
visibleChunks.forEach(chunk => {
if (!chunk.loaded) {
loadChunk(chunk);
}
});
// Unload distant chunks
loadedChunks.forEach(chunk => {
if (!visibleChunks.includes(chunk)) {
unloadChunk(chunk);
}
});
}
```
## React Three Fiber: Suspense
```jsx
import { Suspense } from 'react';
function App() {
return (
<Canvas>
<Suspense fallback={<Loader />}>
<Model />
</Suspense>
</Canvas>
);
}
```
## Performance Budget
| Asset Type | Target |
|------------|--------|
| Initial JS bundle | < 150KB gzipped |
| Hero model | < 500KB compressed |
| Textures | < 1MB total (KTX2) |
| Time to interactive | < 3 seconds |
## Checklist
- [ ] Lazy load 3D content below the fold
- [ ] Code-split Three.js modules
- [ ] Preload critical assets
- [ ] Implement progressive loading
- [ ] Use placeholder geometry during load
- [ ] Offload physics to Web Workers
- [ ] Stream large scenes by chunks
- [ ] Use Suspense in React
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 |