three-best-practices

Name: three-best-practices
Author: emalorenzo

120+ performance rules across 18 categories for optimizing Three.js applications. Organized by priority from fundamental setup (Import Maps, modern renderers) through critical concerns (memory disposal, render loops, draw calls) to specialized topics (WebGPU, TSL shaders, WebXR) Covers both WebGLRenderer and WebGPURenderer with guidance on choosing between them and leveraging TSL (Three.js Shading Language) for shader development Includes practical rules for geometry batching, material reuse, texture compression (Draco, KTX2), lighting optimization, and mobile-specific constraints like pixel ratio limits and shader precision Each rule references detailed documentation with BAD/GOOD code examples, targeting performance goals like sub-100 draw calls per frame and proper resource cleanup to prevent memory leaks

INSTALLATION

npx skills add https://github.com/emalorenzo/three-agent-skills --skill three-best-practices

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

Three.js Best Practices

Comprehensive performance optimization guide for Three.js applications. Contains 120+ rules across 18 categories, prioritized by impact.

Sources & Credits

This skill compiles best practices from multiple authoritative sources:

Official guidelines from Three.js llms branch maintained by mrdoob

100 Three.js Tips by Utsubo - Excellent comprehensive guide covering WebGPU, asset optimization, and performance tips

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

Integrating physics engines

Optimizing for mobile devices

Rule Categories by Priority

Priority

Quick Reference

0. Modern Setup (FUNDAMENTAL)

setup-use-import-maps - Use Import Maps, not old CDN scripts

setup-choose-renderer - WebGLRenderer (default) vs WebGPURenderer (TSL/compute)

setup-animation-loop - Use renderer.setAnimationLoop() not manual RAF

setup-basic-scene-template - Complete modern scene template

1. Memory Management (CRITICAL)

memory-dispose-geometry - Always dispose geometries

memory-dispose-material - Always dispose materials and textures

memory-dispose-textures - Dispose dynamically created textures

memory-dispose-render-targets - Always dispose WebGLRenderTarget

memory-dispose-recursive - Use recursive disposal for hierarchies

memory-dispose-on-unmount - Dispose in React cleanup/unmount

memory-renderer-dispose - Dispose renderer when destroying view

memory-reuse-objects - Reuse geometries and materials

2. Render Loop (CRITICAL)

render-single-raf - Single requestAnimationFrame loop

render-conditional - Render on demand for static scenes

render-delta-time - Use delta time for animations

render-avoid-allocations - Never allocate in render loop

render-cache-computations - Cache expensive computations

render-frustum-culling - Enable frustum culling

render-update-matrix-manual - Disable auto matrix updates for static objects

render-pixel-ratio - Limit pixel ratio to 2

render-antialias-wisely - Use antialiasing judiciously

3. Draw Call Optimization (CRITICAL)

draw-call-optimization - Target under 100 draw calls per frame

geometry-instanced-mesh - Use InstancedMesh for identical objects

geometry-batched-mesh - Use BatchedMesh for varied geometries (same material)

geometry-merge-static - Merge static geometries with BufferGeometryUtils

4. Geometry (HIGH)

geometry-buffer-geometry - Always use BufferGeometry

geometry-merge-static - Merge static geometries

geometry-instanced-mesh - Use InstancedMesh for identical objects

geometry-lod - Use Level of Detail for complex models

geometry-index-buffer - Use indexed geometry

geometry-vertex-count - Minimize vertex count

geometry-attributes-typed - Use appropriate typed arrays

geometry-interleaved - Consider interleaved buffers

5. Materials & Textures (HIGH)

material-reuse - Reuse materials across meshes

material-simplest-sufficient - Use simplest material that works

material-texture-size-power-of-two - Power-of-two texture dimensions

material-texture-compression - Use compressed textures (KTX2/Basis)

material-texture-mipmaps - Enable mipmaps appropriately

material-texture-anisotropy - Use anisotropic filtering for floors

material-texture-atlas - Use texture atlases

material-avoid-transparency - Minimize transparent materials

material-onbeforecompile - Use onBeforeCompile for shader mods (or TSL)

6. Asset Compression (HIGH)

asset-compression - Draco, Meshopt, KTX2 compression guide

asset-draco - 90-95% geometry size reduction

asset-ktx2 - GPU-compressed textures (UASTC vs ETC1S)

asset-meshopt - Alternative to Draco with faster decompression

asset-lod - Level of Detail for 30-40% frame rate improvement

7. Lighting & Shadows (MEDIUM-HIGH)

lighting-limit-lights - Limit to 3 or fewer active lights

lighting-shadows-advanced - PointLight cost, CSM, fake shadows

lighting-bake-static - Bake lighting for static scenes

lighting-shadow-camera-tight - Fit shadow camera tightly

lighting-shadow-map-size - Choose appropriate shadow resolution (512-4096)

lighting-shadow-selective - Enable shadows selectively

lighting-shadow-cascade - Use CSM for large scenes

lighting-shadow-auto-update - Disable autoUpdate for static scenes

lighting-probe - Use Light Probes

lighting-environment - Environment maps for ambient light

lighting-fake-shadows - Gradient planes for budget contact shadows

8. Scene Graph (MEDIUM)

scene-group-objects - Use Groups for organization

scene-layers - Use Layers for selective rendering

scene-visible-toggle - Use visible flag, not add/remove

scene-flatten-static - Flatten static hierarchies

scene-name-objects - Name objects for debugging

object-pooling - Reuse objects instead of create/destroy

9. Shaders GLSL (MEDIUM)

shader-precision - Use mediump for mobile (~2x faster)

shader-mobile - Mobile-specific optimizations (varyings, branching)

shader-avoid-branching - Replace conditionals with mix/step

shader-precompute-cpu - Precompute on CPU

shader-avoid-discard - Avoid discard, use alphaTest

shader-texture-lod - Use textureLod for known mip levels

shader-uniform-arrays - Prefer uniform arrays

shader-varying-interpolation - Limit varyings to 3 for mobile

shader-pack-data - Pack data into RGBA channels

shader-chunk-injection - Use Three.js shader chunks

10. TSL - Three.js Shading Language (MEDIUM)

tsl-why-use - Use TSL instead of onBeforeCompile

tsl-setup-webgpu - WebGPU setup for TSL

tsl-complete-reference - Full TSL type system and functions

tsl-material-slots - Material node properties reference

tsl-node-materials - Use NodeMaterial classes

tsl-basic-operations - Types, operations, swizzling

tsl-functions - Creating TSL functions with Fn()

tsl-conditionals - If, select, loops in TSL

tsl-textures - Textures and triplanar mapping

tsl-noise - Built-in noise functions (mx_noise_float, mx_fractal_noise)

tsl-post-processing - bloom, blur, dof, ao

tsl-compute-shaders - GPGPU and compute operations

tsl-glsl-to-tsl - GLSL to TSL translation

11. WebGPU Renderer (MEDIUM)

webgpu-renderer - Setup, browser support, migration guide

webgpu-render-async - Use renderAsync for compute-heavy scenes

webgpu-feature-detection - Check adapter features

webgpu-instanced-array - GPU-persistent buffers

webgpu-storage-textures - Read-write compute textures

webgpu-workgroup-memory - Shared memory (10-100x faster)

webgpu-indirect-draws - GPU-driven rendering

12. Loading & Assets (MEDIUM)

loading-draco-compression - Use Draco for large meshes

loading-gltf-preferred - Use glTF format

gltf-loading-optimization - Full loader setup with DRACO/Meshopt/KTX2

loading-progress-feedback - Show loading progress

loading-async-await - Use async/await for loading

loading-lazy - Lazy load non-critical assets

loading-cache-assets - Enable caching

loading-dispose-unused - Unload unused assets

13. Core Web Vitals (MEDIUM-HIGH)

core-web-vitals - LCP, FID, CLS optimization for 3D

vitals-lazy-load - Lazy load 3D below the fold with IntersectionObserver

vitals-code-split - Dynamic import Three.js modules

vitals-preload - Preload critical assets with link tags

vitals-progressive-loading - Low-res to high-res progressive load

vitals-placeholders - Show placeholder geometry during load

vitals-web-workers - Offload heavy work to workers

vitals-streaming - Stream large scenes by chunks

14. Camera & Controls (LOW-MEDIUM)

camera-near-far - Set tight near/far planes

camera-fov - Choose appropriate FOV

camera-controls-damping - Use damping for smooth controls

camera-resize-handler - Handle resize properly

camera-orbit-limits - Set orbit control limits

15. Animation (MEDIUM)

animation-system - AnimationMixer, blending, morph targets, skeletal

16. Physics (MEDIUM)

physics-integration - Rapier, Cannon-es integration patterns

physics-compute-shaders - GPU physics with compute shaders

17. WebXR (MEDIUM)

webxr-setup - VR/AR buttons, controllers, hit testing

18. Audio (LOW-MEDIUM)

audio-spatial - PositionalAudio, HRTF, spatial sound

19. Post-Processing (MEDIUM)

postprocessing-optimization - pmndrs/postprocessing guide

postpro-renderer-config - Disable AA, stencil, depth for post

postpro-merge-effects - Combine effects in single pass

postpro-selective-bloom - Selective bloom for performance

postpro-resolution-scaling - Half resolution for 2x FPS

postpro-webgpu-native - TSL-based post for WebGPU

20. Optimization (HIGH)

mobile-optimization - Mobile-specific optimizations and checklist

raycasting-optimization - BVH, layers, GPU picking

21. Production (HIGH)

error-handling-recovery - WebGL context loss and recovery

migration-checklist - Breaking changes by version

22. Debug & DevTools (LOW)

debug-devtools - Complete debugging toolkit

debug-stats-gl - stats-gl for WebGL/WebGPU monitoring

debug-lil-gui - lil-gui for live parameter tweaking

debug-spector - Spector.js for WebGL frame capture

debug-renderer-info - Monitor draw calls and memory

debug-three-mesh-bvh - Fast raycasting with BVH

debug-context-lost - Handle WebGL context loss

debug-animation-loop-profiling - Profile render loop sections

debug-conditional - Remove debug code in production

How to Use

Read individual rule files for detailed explanations and code examples:

rules/setup-use-import-maps.md

rules/memory-dispose-geometry.md

rules/tsl-complete-reference.md

rules/mobile-optimization.md

Each rule file contains:

Brief explanation of why it matters

BAD code example with explanation

GOOD code example with explanation

Additional context and references

Key Patterns

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>

Proper Disposal

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();

    }

  }

}

TSL Basic Usage

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

Mobile Detection

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

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