Three.js & 3D Web Experience

CDN Patterns by Environment

Vanilla HTML (r160 — production default)

<script type="importmap">
{ "imports": {
    "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/"
}}
</script>
<script type="module">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
</script>

Claude Artifact / CodePen (r128 — Cloudflare CDN)

<!-- r128 is the version available on cdnjs.cloudflare.com -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
<script type="module">
import { OrbitControls } from 'https://unpkg.com/[email protected]/examples/jsm/controls/OrbitControls.js';
</script>

⚠️ On r128: never use THREE.CapsuleGeometry (added r142). Use CylinderGeometry + SphereGeometry instead.

React Three Fiber

npm install three @react-three/fiber @react-three/drei

→ See references/interaction-controls.md for R3F patterns.

Canonical Boilerplate

Every Three.js project starts here. Adapt as needed.

import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

// --- Core ---
const scene    = new THREE.Scene();
const camera   = new THREE.PerspectiveCamera(75, innerWidth / innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });

renderer.setSize(innerWidth, innerHeight);
renderer.setPixelRatio(Math.min(devicePixelRatio, 2)); // never above 2
renderer.shadowMap.enabled   = true;
renderer.shadowMap.type      = THREE.PCFSoftShadowMap;
renderer.toneMapping         = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
renderer.outputColorSpace    = THREE.SRGBColorSpace; // r152+ (was outputEncoding)
document.body.appendChild(renderer.domElement);

camera.position.set(0, 1.5, 5);

// --- Controls ---
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.05;

// --- Resize ---
window.addEventListener('resize', () => {
  camera.aspect = innerWidth / innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(innerWidth, innerHeight);
  renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
});

// --- Loop ---
const clock = new THREE.Clock();
function animate() {
  requestAnimationFrame(animate);
  const delta   = clock.getDelta();       // use for mixer.update(delta)
  const elapsed = clock.getElapsedTime(); // use for uniforms.uTime.value
  controls.update();
  renderer.render(scene, camera);
}
animate();

Non-Negotiable Rules

These apply to every Three.js project, no exceptions:

1. Always cap pixel ratio at 2: Math.min(devicePixelRatio, 2)
2. Always use outputColorSpace = THREE.SRGBColorSpace — outputEncoding is deprecated since r152
3. Always dispose geometry, materials and textures when removing objects
4. Always call controls.update() inside the animation loop when enableDamping = true
5. Always set colorSpace = THREE.SRGBColorSpace on albedo/emissive textures; leave linear for normal/roughness/metalness maps
6. Always set castShadow and receiveShadow on both the light AND the mesh
7. Never render above the compositing layer — use renderer.domElement z-index for overlay UIs
8. Check needsUpdate = true after modifying geometry attributes or material uniforms live

Quick Decisions

Which material?

• No lighting needed → MeshBasicMaterial
• Default lit scene → MeshStandardMaterial (PBR)
• Glass / liquid / iridescent → MeshPhysicalMaterial
• Custom effect / animated → ShaderMaterial
• Particles → PointsMaterial

Which camera?

• Most scenes → PerspectiveCamera(75, aspect, 0.1, 1000)
• 2D / isometric / UI → OrthographicCamera

Which light setup?

• Fast start → AmbientLight(0xffffff, 0.5) + DirectionalLight(0xffffff, 1)
• Realistic PBR → RGBELoader HDRI as scene.environment
• Moody/dramatic → PointLight + HemisphereLight with no ambient

Reference Files

Read these when working in the relevant domain. Each is self-contained.