three.js

Common errors

• Uncaught TypeError: Cannot read properties of undefined (reading 'Scene') OR Uncaught ReferenceError: THREE is not defined

  cause Attempting to use `THREE` global or properties of `THREE` when the library hasn't been properly loaded as an ES module or via a script tag, often due to using `require()` or incorrect script order.
  fix Ensure you are using `import * as THREE from 'three';` for modern ES module environments or that the `three.js` script is loaded *before* your application script in a browser environment using `<script src="three.min.js"></script>`.

• Failed to resolve module specifier 'three/examples/jsm/controls/OrbitControls'. Relative references may require a leading './', '../', or '/'

  cause Your module bundler or environment is unable to find the `OrbitControls` module because the path is incomplete or the `.js` extension is missing.
  fix Explicitly include the `.js` extension in your import statement: `import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';`

Warnings

• breaking three.js has a rapid release cycle, typically monthly, and frequently removes deprecated APIs and legacy code. Users are strongly advised to consult the 'Migration Guide' on the GitHub Wiki for each release when upgrading.
  Fix: Always check the official 'Migration Guide' for your target version before upgrading. Update code to use current APIs and practices.
• breaking Modern versions of the 'three' npm package (e.g., r100+) are published as ES Modules (ESM). Direct CommonJS 'require()' will likely fail, especially for core modules.
  Fix: Use ES module syntax: `import * as THREE from 'three';`. Ensure your build environment (e.g., Webpack, Rollup, Vite) is configured to handle ESM or use an older version if CommonJS is strictly required without a bundler.
• gotcha Addon modules (like controls, loaders, post-processing effects) are located in `three/examples/jsm/`. Importing these files often requires a module bundler to correctly resolve file paths and extensions.
  Fix: Configure your bundler (e.g., Webpack's `resolve.extensions`, `module.rules`) to handle `.js` extensions correctly for imported modules, or explicitly include the `.js` extension in import paths: `import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';`.
• breaking The internal format version for Objects and Scenes (used in JSON serialization) may increase with new releases, potentially making scenes saved with older versions incompatible or requiring manual adjustments.
  Fix: Always export/import scenes with the same or newer `three.js` version. Be prepared to update saved scene files if you downgrade or if the format changes significantly between major upgrades.

Install

• npm install three npm
• yarn add three yarn
• pnpm add three pnpm

Imports

• THREE (all exports)
  wrong:

  const THREE = require('three');

  correct:

  import * as THREE from 'three';

  The 'three' package is primarily ESM-only for direct import since major versions. CommonJS 'require' will not work for the modern build.
• Specific components (e.g., Scene, Camera, Renderer)
  wrong:

  import Scene from 'three/src/Scene';

  correct:

  import { Scene, PerspectiveCamera, WebGLRenderer } from 'three';

  Most core components are available as named exports directly from the 'three' package entry point. Avoid importing directly from 'src/'.
• Addon modules (e.g., OrbitControls, GLTFLoader)
  wrong:

  import { OrbitControls } from 'three/src/controls/OrbitControls';

  correct:

  import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

  Addon modules are located under 'three/examples/jsm/'. These require a module bundler (like Webpack or Rollup) to resolve the '.js' extension correctly or an environment that supports bare module specifiers and import maps.

Quickstart

This code initializes a basic 3D scene with a rotating cube, a perspective camera, and a WebGL renderer, animating it in the browser.

import * as THREE from 'three';

const width = window.innerWidth, height = window.innerHeight;

// init

const camera = new THREE.PerspectiveCamera( 70, width / height, 0.01, 10 );
camera.position.z = 1;

const scene = new THREE.Scene();

const geometry = new THREE.BoxGeometry( 0.2, 0.2, 0.2 );
const material = new THREE.MeshNormalMaterial();

const mesh = new THREE.Mesh( geometry, material );
sce.add( mesh );

const renderer = new THREE.WebGLRenderer( { antialias: true } );
renderer.setSize( width, height );
renderer.setAnimationLoop( animate );
document.body.appendChild( renderer.domElement );

// animation

function animate( time ) {
	mesh.rotation.x = time / 2000;
	mesh.rotation.y = time / 1000;

	renderer.render( scene, camera );
}