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
OrbitControlsis 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:
<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 the
HTML and CSS Reference. If using JavaScript modules is new to you, or you need a refresher, check out
JavaScript Modules Reference, both in the appendices.
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:
Then we can use any element of the core by referencing them under the THREE namespace:
THREE namespace
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:
Now instead of hundreds of properties being imported, there are only the three that we need:
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:
OrbitControls
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:
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:
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:
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:
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:
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.
