Chapter 823: Installation (Manual)

Core Idea

Two supported ways to set up a three.js project — npm plus a build tool (recommended for most users) or importing directly from a CDN via an import map — and how addons fit into either.

Key Concepts

• npm + build tool (recommended): installing three.js from npm and using a bundler means local files and npm packages just work, without hand-maintained import maps; production builds are compiled/optimized into a dist/ folder ready to host.
• CDN + import map: no build step required — push source files as-is to a host — but you must keep the import map's dependency versions in sync yourself, and an outage on the CDN takes your site down too.
• Version consistency: all dependencies must come from the same three.js version and the same CDN; mixing sources can duplicate code or break in unexpected ways.
• Addons are imported, not installed separately: core three.js ships the fundamentals; controls, loaders, and post-processing live in the examples/jsm addons directory and just need an explicit import.
• Third-party libraries: some ecosystem projects are genuinely separate packages and do need their own installation.

Code Examples

import * as THREE from "three";
import { OrbitControls } from "three/addons/controls/OrbitControls.js";
import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

const controls = new OrbitControls(camera, renderer.domElement);
const loader = new GLTFLoader();

• What it demonstrates: importing core three.js alongside two commonly used addons (OrbitControls, GLTFLoader).

Key Takeaways

1. For most projects, npm plus a build tool is the recommended setup — it avoids hand-maintaining import maps as dependencies grow.
2. The CDN + import map path needs no build step but pushes dependency-version management onto you and creates a runtime dependency on the CDN's uptime.
3. Always import all three.js-related dependencies from the same version and the same source to avoid duplicate-code or breakage bugs.
4. Addons (controls, loaders, post-processing) ship inside three.js but must be imported explicitly — they're not part of the core three import.

Connects To

• OrbitControls / GLTFLoader: the two addons used as the installation example here.