Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/core-web-vitals.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
perf-zustand-selectors perf-zustand-selectors — a rule file that pushes the agent to subscribe components to individual Zustand slices instead of the whole store, so a component repaints only when the data it reads changes. CX Codex +1 ★ 4,719repo stars geometry-instanced-mesh geometry-instanced-mesh guides AI agents to use THREE.InstancedMesh instead of separate meshes for repeating 3D objects. CX Codex +1 ★ 4,719repo stars webgpu-renderer The webgpu-renderer rule guides Three.js WebGPU setup with a WebGL 2 fallback. Use it when a 3D scene needs compute work, GPU particles, or indirect rendering. CX Codex +1 ★ 4,719repo stars tsl-material-slots tsl-material-slots is a Claude Code rule with a reference to Three.js TSL material slots. It helps write node-based shader logic without mistyping slot names or property types. CX Codex +1 ★ 4,719repo stars postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars timeline-builder timeline-builder is a Claude Code skill that turns JSON event data into interactive HTML timelines with vertical, horizontal, or dual-side layouts. It covers project milestones, release histories, and resumes. CX Codex +1 ★ 4,719repo stars loading-suspense loading-suspense — a rule that keeps async React Three Fiber components inside Suspense, so a model still downloading doesn't leave the canvas blank. CX Codex +1 ★ 4,719repo stars lighting-shadows-advanced The lighting-shadows-advanced rule covers lighting and shadow settings in Three.js with rendering cost in mind. Use it when tuning a scene with several lights or shadow maps. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open