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

Priority Category Impact Prefix

0 Modern Setup & Imports FUNDAMENTAL setup-

1 Memory Management & Dispose CRITICAL memory-

2 Render Loop Optimization CRITICAL render-

3 Geometry & Buffer Management HIGH geometry-

4 Material & Texture Optimization HIGH material-

5 Lighting & Shadows MEDIUM-HIGH lighting-

6 Scene Graph Organization MEDIUM scene-

7-8 Shader Best Practices MEDIUM shader- , tsl-

9-17 Loading, Camera, Animation, Physics, WebXR, Audio, Mobile, Production, Debug VARIES

Quick Reference

Modern Import Maps

<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:

function 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)

// 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)

// 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)

// 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

const 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)

import { 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

Pattern Benefit

Use InstancedMesh 100x draw calls → 1 draw call

Merge static geometries Reduce draw calls

Use LOD (Level of Detail) Performance at distance

Enable frustum culling Skip off-screen objects

Use texture atlases Reduce material switches

Bake lighting Eliminate runtime shadows

Anti-Patterns

Anti-Pattern Fix

Creating objects in render loop Cache and reuse

Not disposing resources Always call .dispose()

Using BufferGeometry constructor Use specific geometry classes

Too many lights Limit to 3-4 dynamic lights

High pixel ratio on mobile Cap at 1.5-2

Attribution

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