---

name: three-js description: Three.js performance optimization - 100+ rules for memory, rendering, geometry, materials, WebGPU, and WebXR.

Three.js Best Practices

Comprehensive performance optimization guide for Three.js applications with 100+ rules across 17 categories.

When to Apply

Reference these guidelines when:

• Setting up a new Three.js project
• Writing or reviewing Three.js code
• Optimizing performance or fixing memory leaks
• Working with custom shaders (GLSL or TSL)
• Implementing WebGPU features
• Building VR/AR experiences with WebXR

Rule Categories by Priority

Quick Reference

Modern Import Maps

Copy<script type="importmap">
{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.182.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.182.0/examples/jsm/",
    "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.182.0/build/three.tsl.js"
  }
}
</script>

Memory Management (CRITICAL)

Always dispose resources:

Copyfunction disposeObject(obj) {
  if (obj.geometry) obj.geometry.dispose();
  if (obj.material) {
    if (Array.isArray(obj.material)) {
      obj.material.forEach(m => m.dispose());
    } else {
      obj.material.dispose();
    }
  }
}

// Recursive disposal for hierarchies
function disposeHierarchy(obj) {
  obj.traverse(child => disposeObject(child));
}

Render Loop (CRITICAL)

Copy// Use setAnimationLoop, not manual RAF
renderer.setAnimationLoop(animate);

// Never allocate in render loop
const _tempVector = new THREE.Vector3();  // Reuse outside loop

function animate(time) {
  // Use cached objects
  _tempVector.set(0, 1, 0);
  
  // Use delta time for animations
  const delta = clock.getDelta();
  mixer.update(delta);
  
  renderer.render(scene, camera);
}

Geometry (HIGH)

Copy// Use InstancedMesh for identical objects
const mesh = new THREE.InstancedMesh(geometry, material, count);
const matrix = new THREE.Matrix4();

for (let i = 0; i < count; i++) {
  matrix.setPosition(positions[i]);
  mesh.setMatrixAt(i, matrix);
}
mesh.instanceMatrix.needsUpdate = true;

Materials & Textures (HIGH)

Copy// Reuse materials
const sharedMaterial = new THREE.MeshStandardMaterial({ color: 0xff0000 });

// Use compressed textures
const ktx2Loader = new KTX2Loader()
  .setTranscoderPath('path/to/basis/')
  .detectSupport(renderer);

// Power-of-two texture dimensions
// 512x512, 1024x1024, 2048x2048

Mobile Optimization

Copyconst isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);

// Limit pixel ratio
renderer.setPixelRatio(Math.min(window.devicePixelRatio, isMobile ? 1.5 : 2));

// Reduce shadow map size on mobile
if (isMobile) {
  light.shadow.mapSize.width = 512;
  light.shadow.mapSize.height = 512;
}

TSL (Three.js Shading Language)

Copyimport { texture, uv, color, time, sin } from 'three/tsl';

const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture(map).mul(color(0xff0000));
material.colorNode = color(0x00ff00).mul(sin(time).mul(0.5).add(0.5));

Key Patterns

Anti-Patterns

Attribution

Based on emalorenzo/three-agent-skills three-best-practices - 53+ installs. Official guidelines from Three.js llms branch maintained by mrdoob.