Three.js - Installation

Three.js - Modern Installation and Setup

To build robust and optimized Three.js applications, a modern development environment is essential. While you can use Three.js via a simple script tag, the recommended approach involves using Node.js, a package manager, and a build tool.

The Modern Way: Using a Build Tool (Recommended)

This method gives you superpowers: dependency management (easily add and update three and other libraries), code bundling (optimizing your code for production), hot module replacement (see changes instantly without a page refresh), and the ability to use modern JavaScript features seamlessly.

Step 1: Set Up Your Project with Vite

Vite is a fast and simple build tool that is perfect for Three.js development. First, make sure you have Node.js installed (which includes npm).

Open your terminal and run these commands:

# 1. Create a new Vite project (choose 'Vanilla' and 'JavaScript')
npm create vite@latest my-threejs-project

# 2. Navigate into your new project directory
cd my-threejs-project

# 3. Install the necessary packages
npm install

# 4. Install Three.js as a dependency
npm install three

# 5. Start the development server
npm run dev

Vite will start a local server, and you can see your app in the browser. Now you can edit the main.js file and start coding!

Step 2: Import Three.js into Your Code

In your main.js file, you can now import Three.js using ES6 module syntax.

main.js

import * as THREE from 'three';

// You can also import specific components you need, like OrbitControls
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

// Your Three.js code starts here...
const scene = new THREE.Scene();
// ...

Step 3: Version Control with Git

It is a best practice to use a version control system like Git to track your changes. Initialize a repository in your project folder:

# In your project folder
git init
git add .
git commit -m "Initial commit with Three.js setup"

The Quick Way: Using a CDN

For very simple tests or online code sandboxes (like CodePen), you can use a Content Delivery Network (CDN) to include Three.js directly in your HTML. This method does not require Node.js or a build step.

This is not recommended for production applications because it’s less performant (no tree-shaking) and makes managing dependencies difficult.

<!DOCTYPE html>
<html>
  <head>
    <title>Three.js CDN Example</title>
  </head>
  <body>
    <script type="importmap">
      {
        "imports": {
          "three": "https://unpkg.com/three@latest/build/three.module.js",
          "three/examples/jsm/": "https://unpkg.com/three@latest/examples/jsm/"
        }
      }
    </script>
    <script type="module">
      import * as THREE from 'three';
      import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

      // Your code here...
    </script>
  </body>
</html>

Note the use of importmap, which is the modern way to handle ES modules directly in the browser.

The Legacy Way: Manual Download

Status: Deprecated. This method involves downloading the Three.js source files from GitHub and including them in your project manually. It is highly discouraged because:

• Versioning Hell: Updating to a new version of Three.js is a manual, error-prone process.
• No Optimization: You are forced to include the entire library, even the parts you don’t use.
• Incompatible with Modern Tools: It does not work well with modern JavaScript modules and bundlers.

Always prefer the modern build tool approach for any project you plan to maintain or grow.