Three Best Practices

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

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)