Discover three.js is now open source!
Word Count:1444, reading time: ~7minutes

How to Include three.js in Your Projects

There are several ways to include three.js in your JavaScript application, some simple, some a little more complex, but they all boil down to this: you need to include the three.js core in your project, which you can find in this file on the three.js repo:

In addition to the core file, we’ll often add plugins such as camera controls or post-processing. You can find plugins in the examples/jsm folder on the repo, and including them works in much the same way as for the core file. For the rest of this chapter, we’ll use the OrbitControls plugin (a popular camera controls plugin) for demonstration, which you can find on the repo here:

Open up the editor on this page by clicking the icon, and you’ll see that we have included these two files inside the vendor/ folder:

  • The core is in vendor/three/build/three.module.js
  • OrbitControls is in vendor/three/examples/jsm/controls/OrbitControls.js.

We have also set up a very simple web page consisting of these three files:

  • index.html
  • src/main.js
  • styles/main.css

Check out index.html now, and you’ll see that we have referenced main.js in the <head> section:

index.html: referencing the main JavaScript file
    


<script type="module" src="./src/main.js"></script>



  

Take special notice of type="module", which we’re using to tell the browser the linked file is a JavaScript module. If anything in index.html is unfamiliar to you, check out A.1: HTML and CSS Used in This Book. If using JavaScript modules is new to you, or you need a refresher, check out A.4: JavaScript Modules.

Importing three.js Modules

The core and OrbitControls plugins are JavaScript modules. To use them, first, we need to import them into main.js, so open up that file now. Over the rest of this chapter, we’ll demonstrate various ways to import three.module.js and OrbitControls.js here.

Importing the three.js Core

The three.js core contains hundreds of classes such as cameras, materials, geometries, textures, lights, shadows, the animation system, various loaders, audio, the renderer, 2D shapes, helpers, fog, and so on. We’ll never need to use all of them at once, and in fact, it’s almost certain you’ll never need to use all of them across an entire application, no matter how big it is. So, for this chapter, let’s assume we want to import just three classes from three.module.js: the PerspectiveCamera, the MeshStandardMaterial, and the WebGLRenderer.

Import the Entire three.js Core

The simplest approach is to import everything from the three.js core into main.js under the THREE namespace:

main.js: import the entire three.js core
    
import \* as THREE from './vendor/three/build/three.module.js';

  

Then we can use any element of the core by referencing them under the THREE namespace:

main.js: accessing classes from the core under the THREE namespace
    


THREE.PerspectiveCamera;
THREE.MeshStandardMaterial;
THREE.Texture;
// ... and hundreds more



  

Import Individual Components from the Core

However, in this book we’ll prefer to import only the classes that we need in any given module:

main.js: importing class as we need them
    


import {
  PerspectiveCamera,
  MeshStandardMaterial,
  WebGLRenderer,
} from "./vendor/three/build/three.module.js";



  

Now instead of hundreds of properties being imported, there are only the three that we need:

main.js: accessing individually imported classes
    


PerspectiveCamera;
MeshStandardMaterial;
WebGLRenderer;



  

Doing this forces us to think more carefully about the classes we’re using in a given module, which means we’re more likely to follow best practices and keep our modules small and focused. We can also avoid using the THREE namespace this way.

Importing Plugins

The OrbitControls.js module contains a single export, the OrbitControls class. Importing this works the same way as importing classes from the core:

main.js: import OrbitControls
    


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



  

Now the OrbitControls class is available within main.js. With both the core files and a camera controls plugin, we are ready to start building our app.

How to Obtain the three.js Files

Not so fast! How do we get our hands on the files in the first place? In the editor, we have already got the files for you, but if you’re working locally, you’ll have to handle that yourself. Here are three common approaches.

1: Download Them All!

The easiest method is to download the entire three.js Github repo onto your computer. Here’s the latest release of three.js as a zip file. Download it and look inside the build/ and examples/jsm/ folders and you’ll find the necessary files. Extract everything from the zip file into vendor/ and proceed as described above.

If you’re new to web development, you’ll probably find this method the easiest. You can graduate to a more sophisticated approach later.

2: Link to the files from a CDN

A second approach is to link the files from a CDN (Content Delivery Network), which is a remote site dedicated to hosting files so you can use them in a web page without downloading them first. There are lots of CDNs around, however, many of them don’t support loading modules. One that does is skypack.dev which allows you to load any published NPM package. You can find the core three.module.js file here:

Note that we’re specifying the version. You can also leave out the version which will always return the latest version

However, doing this means that a new release of three.js might break your app while you’re not looking so it’s a good idea to alway lock down the version.

When it comes to loading plugins, you can reference them using the structure of the repo, so you’ll find OrbitControls.js here:

To find a file from the repo, take the URL from GitHub (such as examples/jsm/controls/OrbitControls.js) and prepend https://cdn.skypack.dev/0.{version}.0, where {version} is the release of three.js that you’re using.

At the time of writing, the latest version is r132, and the final .2 in 0.132.2 means there have been some hotfixes applied to the release after publising it to NPM. A new version is released every month. It’s not necessary to use the latest version, but it is necessary to use the same version for the main build file and any extensions you use.

Importing the files from a CDN works the same way as importing them from your local file system, except that now we are loading the files from skypack.dev instead of from our hard drive:

main.js: importing three.js files from a CDN
    


import {
  Camera,
  Material,
  Texture,
} from "https://cdn.skypack.dev/[email protected]";

import { OrbitControls } from "https://cdn.skypack.dev/[email protected]/examples/jsm/controls/OrbitControls.js";



  

3: Install three.js as an NPM package

Note: This section assumes that you have a basic understanding of how JavaScript package management works. If you don’t, get the files using another method for now.

three.js is also available as a package on NPM. If you have Node.js and NPM (Node Package Manager) installed on your computer, you can open a command prompt and enter the following commands:

Command prompt: install the three npm package
    
// set up a project
npm init

// once the project is set up, install the three npm package
npm install --save three

  

Once again, importing the files works the same way, except that now we can replace the big ugly CDN URL with the name of the package, in this case, three:

main.js: importing class from the three.js core using the NPM package
    
import {
Camera,
Material,
Texture,
} from 'three';

  

When you do this, your bundler will automatically resolve three to the main export of the package, in this case three/build/three.module.js. You can also import this file directly, there’s no difference:

main.js: directly referencing the core file from the three package
    
import {
Camera,
Material,
Texture,
} from 'three/build/three.module.js';

  

Importing plugins is not quite so convenient as an NPM package can only have one main file. To import OrbitControls, we need to reference the containing module directly:

main.js: importing three.js plugins using the NPM package
    
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';

  

There are many bundlers available, such as Rollup, Webpack, ESBuild, and Parcel, and setting these up is beyond the scope of this book. However, they all resolve modules in the same way so you can write this code and then bundle it using whichever one you like.

Import Style Used in this Book

In the examples throughout this book, we’ll use NPM style imports since these are both the shortest way of writing the import statements, and the style you are most likely to encounter in a professional setting.

In most chapters, in the editor, you can switch between NPM and CDN imports (using skypack.dev). However, if you download the code from the editor, the downloaded code will use CDN imports. This means you can use the downloaded code immediately on your local computer without the trouble of setting up a bundler or installing NPM packages. You will, however, need to set up a local development server.

Import Style
Selected Texture