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
.claude/rules/migration-checklist.mdWhat 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
OrbitControlsimport error after Three.js update - replace
BoxBufferGeometrywith the current constructor - switch from deprecated
outputEncodingtocolorSpace - adapt code to shadow and PBR changes in r182–r183
Example prompts for the agent
- Update Three.js imports in
scene.jsfor r170 - Replace deprecated geometry constructors in
models/ - Check for
BoxBufferGeometryissues — the agent throws a constructor error
How to install migration-checklist
Manually: put the files in place
.claude/rules/migration-checklist.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/migration-checklist.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/migration-checklist.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/migration-checklist.mdManually: put the files in place
.clinerules/migration-checklist.mdStep 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