Skip to main content
rule CX Codex

migration-checklist — Claude Code rule: Three.js migration guide

migration-checklist teaches the agent how to migrate code when Three.js updates. Lists breaking changes from r125 onwards and current import paths.

MIT ★ 4,719 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/migration-checklist.md
Open on GitHub

What migration-checklist does

The rule maps Three.js API breaks since r125: removed constructors (BoxBufferGeometry is now BoxGeometry), renamed properties (outputEncoding became outputColorSpace), and changes in light and shadow behavior. The agent sees old and new syntax side by side — imports via three/webgpu instead of addons/renderers/webgpu/, boolean vertexColors replacing the constant, and the new animation loop through setAnimationLoop(). For WebGPU, it lists the required TSL paths and default PBR settings.

Each break includes before-and-after code, diagnostics for common errors like "X is not a constructor", and default values for decay, bias, and roughness. No external dependencies — the rule applies to Three.js itself.

What it helps with

  • fix OrbitControls import error after Three.js update
  • replace BoxBufferGeometry with the current constructor
  • switch from deprecated outputEncoding to colorSpace
  • adapt code to shadow and PBR changes in r182–r183

Example prompts for the agent

  • Update Three.js imports in scene.js for r170
  • Replace deprecated geometry constructors in models/
  • Check for BoxBufferGeometry issues — the agent throws a constructor error

How to install migration-checklist

Manually: put the files in place

.claude/rules/migration-checklist.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about migration-checklist

How to install migration-checklist in Claude Code?

Place the file in .claude/rules/migration-checklist.md — the agent picks it up automatically.

What does migration-checklist do?

Shows the agent Three.js breaking changes from r125: which constructors were removed, how to rewrite imports, and where renderer and material properties moved.

Which Three.js versions does the rule cover?

From r125 to r183. Most detail on r170 (imports), r147 (color and light), and r180–r183 (WebGPU and PBR).

Source text

migration-checklist.md · MIT
# Migration Checklist

Breaking changes and migration guide for Three.js versions.

## Recent Changes (r180-r183)

### r182 → r183

- Shadow quality improved in WebGPURenderer; reduce/remove bias values
- RoomEnvironment scene position updated; lighting may differ
- Sky/SkyMesh legacy gamma correction removed
- MeshPostProcessingMaterial removed

### r181 → r182

- `PCFSoftShadowMap` deprecated with WebGLRenderer; use `PCFShadowMap`
- WebGPURenderer: `colorBufferType` → `outputBufferType`
- VOXLoader.load() restructured

### r180 → r181

- Indirect specular light computation improved for PBR
- Rough PBR materials now appear brighter
- `renderAsync()`/`computeAsync()` deprecated; use sync versions
- TSL: `PI2` → `TWO_PI`
- New JSDoc-based API documentation

## Import Changes (r170+)

### BAD - Deprecated

```javascript
import { WebGPURenderer } from 'three/addons/renderers/webgpu/WebGPURenderer.js';
import { MeshStandardNodeMaterial } from 'three/addons/nodes/materials/...';
```

### GOOD - Current

```javascript
import * as THREE from 'three/webgpu';  // WebGPURenderer and NodeMaterials
import { ... } from 'three/tsl';         // TSL functions
```

## Color Management (r151+)

### BAD - Old API

```javascript
renderer.outputEncoding = THREE.sRGBEncoding;
texture.encoding = THREE.sRGBEncoding;
```

### GOOD - Current API

```javascript
renderer.outputColorSpace = THREE.SRGBColorSpace;
texture.colorSpace = THREE.SRGBColorSpace;
// ColorManagement.enabled = true by default
```

## Geometry Changes (r125+)

### Removed

```javascript
// REMOVED - use BufferGeometry
const geometry = new THREE.Geometry();
```

### Aliases Removed

```javascript
// These no longer exist
BoxBufferGeometry → BoxGeometry
SphereBufferGeometry → SphereGeometry
PlaneBufferGeometry → PlaneGeometry
// Just use BoxGeometry, SphereGeometry, etc.
```

## Light Decay (r147+)

```javascript
// Default decay is now 2 (physically correct)
const light = new THREE.PointLight(0xffffff, 1);
light.decay = 2; // DEFAULT

// To restore old behavior:
light.decay = 1;
```

## Material Changes (r147+)

```javascript
// vertexColors is now boolean
material.vertexColors = true;  // CORRECT

// OLD:
// material.vertexColors = THREE.VertexColors; // REMOVED
```

## Renderer Changes

### setAnimationLoop

```javascript
// GOOD - Modern way
renderer.setAnimationLoop(animate);

// OLD - Still works but less preferred
function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();
```

### XR Animation Loop

```javascript
// For WebXR, MUST use setAnimationLoop
renderer.xr.enabled = true;
renderer.setAnimationLoop(animate);
```

## Version Check

```javascript
console.log('Three.js version:', THREE.REVISION);

// Example: "182"
if (parseInt(THREE.REVISION) < 170) {
  console.warn('Please update Three.js to r170+');
}
```

## Common Migration Issues

### Issue: "X is not a constructor"

```javascript
// Check import path
// OLD:
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';

// NEW:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
```

### Issue: Colors look different

```javascript
// Color management is now enabled by default
// If colors look washed out:
THREE.ColorManagement.enabled = false; // Revert to old behavior (not recommended)

// Better: Fix your color values for linear workflow
```

### Issue: Materials appear different

```javascript
// PBR materials changed in r180+
// Rough surfaces are now brighter
// Adjust roughness values if needed
material.roughness = 0.6; // May need to increase
```

### Issue: Shadows look wrong

```javascript
// Shadow bias may need adjustment
light.shadow.bias = -0.0001; // r183+ may need smaller values
```

## Quick Migration Checklist

- [ ] Update import paths (`addons/` instead of `examples/jsm/`)
- [ ] Replace `encoding` with `colorSpace`
- [ ] Remove BufferGeometry suffix (BoxGeometry, not BoxBufferGeometry)
- [ ] Check light decay values
- [ ] Update vertexColors to boolean
- [ ] For WebGPU: use `three/webgpu` and `three/tsl` imports
- [ ] Test shadows and adjust bias if needed
- [ ] Verify PBR material appearance

## References

- [Three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)
- [Three.js Releases](https://github.com/mrdoob/three.js/releases)

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars timeline-builder timeline-builder is a Claude Code skill that turns JSON event data into interactive HTML timelines with vertical, horizontal, or dual-side layouts. It covers project milestones, release histories, and resumes. CX Codex +1 ★ 4,719repo stars loading-suspense loading-suspense — a rule that keeps async React Three Fiber components inside Suspense, so a model still downloading doesn't leave the canvas blank. CX Codex +1 ★ 4,719repo stars lighting-shadows-advanced The lighting-shadows-advanced rule covers lighting and shadow settings in Three.js with rendering cost in mind. Use it when tuning a scene with several lights or shadow maps. CX Codex +1 ★ 4,719repo stars audio-spatial The audio-spatial rule for Claude Code provides Three.js 3D audio patterns for source positioning, distance falloff, and response to user interaction. CX Codex +1 ★ 4,719repo stars debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars tsl-post-processing A reference rule for TSL post-processing in Three.js: chain effects onto postProcessing.outputNode instead of stacking EffectComposer passes. CX Codex +1 ★ 4,719repo stars tsl-compute-shaders tsl-compute-shaders guides the agent in writing WebGPU compute shaders with Three.js TSL for GPGPU tasks like particle systems and physics. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open