core-web-vitals — Claude Code rule: what it does, how to install
core-web-vitals is a Claude Code rule for loading Three.js models and textures without letting heavy 3D delay first paint or degrade LCP, FID and CLS.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/core-web-vitals.mdWhat core-web-vitals does
The rule keeps heavy 3D off the critical load path. Anything below the fold waits for an IntersectionObserver before the scene starts, Three.js modules arrive through dynamic import(), and critical .glb and .ktx2 files get a <link rel="preload"> tag.
Each section ships a short snippet. Progressive loading paints a low-res model first, swaps in the high-res one and disposes the old geometry. A wireframe box fills the gap while the real asset downloads. Physics moves to a Web Worker, chunks stream in by camera position, and React Three Fiber gets a Suspense wrapper. A budget table closes the file: initial JS under 150KB gzipped, hero model under 500KB, textures under 1MB in KTX2, interactive under 3 seconds.
Scope is Three.js, so a project without 3D has nothing here to tune. Treat the table as numbers to check against during review, not thresholds the file enforces.
What it helps with
- keep a 3D scene off the critical load path
- split the Three.js bundle into dynamic imports
- show a placeholder while the model downloads
- move physics work into a Web Worker
- set size budgets for models and textures
Example prompts for the agent
- Audit my Three.js scene against the core-web-vitals rule and list what blows the budget.
- Rework the model loading: low-res first, then swap in the high-res version and dispose the old geometry.
- Move the physics loop off the main thread into a Web Worker, per the core-web-vitals rule.
How to install core-web-vitals
Manually: put the files in place
.claude/rules/core-web-vitals.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/core-web-vitals.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/core-web-vitals.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/core-web-vitals.mdManually: put the files in place
.clinerules/core-web-vitals.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about core-web-vitals
How do I install core-web-vitals in Claude Code?
Create .claude/rules/core-web-vitals.md and paste the rule text into it.
What does core-web-vitals do?
It spells out how to load 3D content without hurting LCP, FID and CLS: lazy loading below the fold, code splitting of Three.js modules, asset preload, and a low-res model swapped for the full one.
Which stack does the rule target?
Three.js scenes, including React apps that render through React Three Fiber, which gets its own Suspense example. Without 3D on the page there is little to apply.
Source text
core-web-vitals.md · MIT
# 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
© zebbern · MIT · zebbern/claude-code-guide