While importing three.js via script tags is a great way to get up and running fast, it has a few drawbacks for longer lived projects, for example:
<ul>
<li>You have to manually fetch and include a copy of the library as part of your project's source code</li>
<li>Updating the library's version is a manual process</li>
<li>When checking in a new version of the library your version control diffs are cluttered by the many lines of the build file</li>
</ul>
</p>
<p>Using a dependency manager like npm avoids these caveats by allowing you to simply download and import your desired version of the library onto your machine.</p>
<h2>Installation via npm</h2>
<p>Three.js is published as an npm module, see: [link:https://www.npmjs.com/package/three npm]. This means all you need to do to include three.js into your project is run "npm install three"</p>
<h2>Importing the module</h2>
<p>Assuming that you're bundling your files with a tool such as [link:https://webpack.github.io/ Webpack] or [link:https://github.com/substack/node-browserify Browserify], which allow you to "require('modules')" in the browser by bundling up all of your dependencies.</p>
<p>
You should now be able to import the module into your source files and continue to use it as per normal.
</p>
<code>
var THREE = require('three');
var scene = new THREE.Scene();
...
</code>
<p>
You're also able to leverage [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import ES6 import syntax]:
</p>
<code>
import * as THREE from 'three';
const scene = new THREE.Scene();
...
</code>
<p>
or if you wish to import only select parts of three.js library, for example Scene:
</p>
<code>
import { Scene } from 'three';
const scene = new Scene();
...
</code>
<h2>Importable Examples</h2>
<p>
The core of three.js is focused on the most important components of a 3D engine. Many other components like loaders or controls are part of the
examples directory. three.js ensures that these files are kept in sync with the core but users have to import them separately if they are required
for a project. You can find them in the [link:https://github.com/mrdoob/three.js/tree/master/examples/jsm examples/jsm] directory. If you install three.js
via npm, import example files like so:
</p>
<code>
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
</code>
<p>
Note: When using code from the examples directory, it's important that all files match the version of
your three.js main file. For example, it's not acceptable to use *GLTFLoader* and *OrbitControls* from R96 together
You can install three.js with [link:https://www.npmjs.com/ npm] and modern build tools, or get started quickly with just static hosting or a CDN. For most users, installing from npm is the best choice.
</p>
<p>
Whichever you choose, be consistent and import all files from the same version of the library. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways.
</p>
<p>
All methods of installing three.js depend on ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules], which allow you to include only the parts of the library needed in the final project.
</p>
<h2>Install from npm</h2>
<p>
To install the [link:https://www.npmjs.com/package/three three] npm module, open a terminal window in your project folder and run:
</p>
<code>
npm install --save three
</code>
<p>
The package will be downloaded and installed. Then you're ready to import it in your code:
When installing from npm, you'll almost always use some sort of [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] to combine all of the packages your project requires into a single JavaScript file. While any modern JavaScript bundler can be used with three.js, the most popular choice is [link:https://webpack.js.org/ webpack].
</p>
<p>
Not all features are accessed directly through the <em>three</em> module (also called a "bare import"). Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see <em>Examples</em> below.
</p>
<p>
Learn more about npm modules from [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm].
</p>
<h2>Install from CDN or static hosting</h2>
<p>
The three.js library can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use <em>type="module"</em> as shown below:
</p>
<code>
<script type="module">
// Find the latest version by visiting https://unpkg.com/three. The URL will
// redirect to the newest stable release.
import * as THREE from 'https://unpkg.com/three@<VERSION>/build/three.module.js';
const scene = new THREE.Scene();
</script>
</code>
<p>
Not all features are accessed through the <em>build/three.module.js</em> module. Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see <em>Examples</em> below.
</p>
<h2>Examples</h2>
<p>
The core of three.js is focused on the most important components of a 3D engine. Many other useful components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] directory. They are referred to as "examples," because while you can use them off the shelf, they're also meant to be remixed and customized. These components are always kept in sync with the core library, whereas similar third-party packages on npm are maintained by different people and may not be up to date.
</p>
<p>
Examples do not need to be <em>installed</em> separately, but do need to be <em>imported</em> separately. If three.js was installed with npm, you can load the [page:OrbitControls] component with:
</p>
<code>
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls();
</code>
<p>
If three.js was installed from a CDN, use the same CDN to install other components:
</p>
<code>
<script type="module">
// Find the latest version by visiting https://unpkg.com/three. The URL will
// redirect to the newest stable release.
import { OrbitControls } from 'https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls();
</script>
</code>
<p>
It's important that all files use the same version. Do not import different examples from different versions, or use examples from a different version than the three.js library itself.
</p>
<h2>Compatibility</h2>
<h3>CommonJS imports</h3>
<p>
While most modern JavaScript bundlers now support ES modules by default, some older build tools might not. In those cases you can likely configure the bundler to understand ES modules: [link:http://browserify.org/ Browserify] just needs the [link:https://github.com/babel/babelify babelify] plugin, for example.
</p>
<h3>Node.js</h3>
<p>
Using three.js in [link:https://eloquentjavascript.net/20_node.html Node.js] can be difficult, for two reasons:
</p>
<p>
First, because three.js is built for the web, it depends on browser and DOM APIs that don't always exist Node.js. Some of these issues can be resolved by using shims like [link:https://github.com/stackgl/headless-gl headless-gl], or by replacing components like [page:TextureLoader] with custom alternatives. Other DOM APIs may be deeply intertwined with the code that uses them, and will be harder to work around. We welcome simple and maintainable pull requests to improve Node.js support, but recommend opening an issue to discuss your improvements first.
</p>
<p>
Second, Node.js support for ES modules is ... complicated. As of Node.js v12, the core library can be imported as a CommonJS module, with <em>require('three')</em>. However, most example components in <em>examples/jsm</em> cannot. Future versions of Node.js may resolve this, but in the meantime you may need to use workarounds like [link:https://github.com/standard-things/esm esm] to enable your Node.js application to recognize ES modules.
The core of three.js is focused on the most important components of a 3D engine. Many other components like loaders or controls are part of the
examples directory. three.js ensures that these files are kept in sync with the core but users have to import them separately if they are required
for a project. You can find them in the [link:https://github.com/mrdoob/three.js/tree/master/examples/jsm examples/jsm] directory. If you install three.js
via npm, import example files like so:
</p>
<code>
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
You can install three.js with [link:https://www.npmjs.com/ npm] and modern build tools, or get started quickly with just static hosting or a CDN. For most users, installing from npm is the best choice.
</p>
<p>
Whichever you choose, be consistent and import all files from the same version of the library. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways.
</p>
<p>
All methods of installing three.js depend on ES modules (see [link:https://eloquentjavascript.net/10_modules.html#h_hF2FmOVxw7 Eloquent JavaScript: ECMAScript Modules], which allow you to include only the parts of the library needed in the final project.
</p>
<h2>Install from npm</h2>
<p>
To install the [link:https://www.npmjs.com/package/three three] npm module, open a terminal window in your project folder and run:
</p>
<code>
npm install --save three
</code>
<p>
The package will be downloaded and installed. Then you're ready to import it in your code:
When installing from npm, you'll almost always use some sort of [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC bundling tool] to combine all of the packages your project requires into a single JavaScript file. While any modern JavaScript bundler can be used with three.js, the most popular choice is [link:https://webpack.js.org/ webpack].
</p>
<p>
Not all features are accessed directly through the <em>three</em> module (also called a "bare import"). Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see <em>Examples</em> below.
</p>
<p>
Learn more about npm modules from [link:https://eloquentjavascript.net/20_node.html#h_J6hW/SmL/a Eloquent JavaScript: Installing with npm].
</p>
<h2>Install from CDN or static hosting</h2>
<p>
The three.js library can be used without any build system, either by uploading files to your own web server or by using an existing CDN. Because the library relies on ES modules, any script that references it must use <em>type="module"</em> as shown below:
</p>
<code>
<script type="module">
// Find the latest version by visiting https://unpkg.com/three. The URL will
// redirect to the newest stable release.
import * as THREE from 'https://unpkg.com/three@<VERSION>/build/three.module.js';
const scene = new THREE.Scene();
</script>
</code>
<p>
Not all features are accessed through the <em>build/three.module.js</em> module. Other popular parts of the library — such as controls, loaders, and post-processing effects — must be imported from the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] subfolder. To learn more, see <em>Examples</em> below.
</p>
<h2>Examples</h2>
<p>
The core of three.js is focused on the most important components of a 3D engine. Many other useful components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm examples/jsm] directory. They are referred to as "examples," because while you can use them off the shelf, they're also meant to be remixed and customized. These components are always kept in sync with the core library, whereas similar third-party packages on npm are maintained by different people and may not be up to date.
</p>
<p>
Examples do not need to be <em>installed</em> separately, but do need to be <em>imported</em> separately. If three.js was installed with npm, you can load the [page:OrbitControls] component with:
</p>
<code>
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls();
</code>
<p>
If three.js was installed from a CDN, use the same CDN to install other components:
</p>
<code>
<script type="module">
// Find the latest version by visiting https://unpkg.com/three. The URL will
// redirect to the newest stable release.
import { OrbitControls } from 'https://unpkg.com/three@<VERSION>/examples/jsm/controls/OrbitControls.js';
const controls = new OrbitControls();
</script>
</code>
<p>
It's important that all files use the same version. Do not import different examples from different versions, or use examples from a different version than the three.js library itself.
</p>
<h2>Compatibility</h2>
<h3>CommonJS imports</h3>
<p>
While most modern JavaScript bundlers now support ES modules by default, some older build tools might not. In those cases you can likely configure the bundler to understand ES modules: [link:http://browserify.org/ Browserify] just needs the [link:https://github.com/babel/babelify babelify] plugin, for example.
</p>
<h3>Node.js</h3>
<p>
Using three.js in [link:https://eloquentjavascript.net/20_node.html Node.js] can be difficult, for two reasons:
</p>
<p>
First, because three.js is built for the web, it depends on browser and DOM APIs that don't always exist Node.js. Some of these issues can be resolved by using shims like [link:https://github.com/stackgl/headless-gl headless-gl], or by replacing components like [page:TextureLoader] with custom alternatives. Other DOM APIs may be deeply intertwined with the code that uses them, and will be harder to work around. We welcome simple and maintainable pull requests to improve Node.js support, but recommend opening an issue to discuss your improvements first.
</p>
<p>
Second, Node.js support for ES modules is ... complicated. As of Node.js v12, the core library can be imported as a CommonJS module, with <em>require('three')</em>. However, most example components in <em>examples/jsm</em> cannot. Future versions of Node.js may resolve this, but in the meantime you may need to use workarounds like [link:https://github.com/standard-things/esm esm] to enable your Node.js application to recognize ES modules.
