Add module import doc

mrdoob · Jul 16, 2017 · e2256a3 · e2256a3 · goretkin · Aug 13, 2017
1 parent 943c345
commit e2256a3
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -19,7 +19,7 @@ The aim of the project is to create an easy to use, lightweight, 3D library. The
 
 ### Usage ###
 
-Download the [minified library](http://threejs.org/build/three.min.js) and include it in your html.
+Download the [minified library](http://threejs.org/build/three.min.js) and include it in your html, or install and import it as a [module](http://threejs.org/docs/#manual/introduction/Import-via-modules),
 Alternatively see [how to build the library yourself](https://github.com/mrdoob/three.js/wiki/Build-instructions).
 
 ```html

diff --git a/docs/list.js b/docs/list.js
@@ -4,6 +4,7 @@ var list = {
 
 		"Getting Started": {
 			"Creating a scene": "manual/introduction/Creating-a-scene",
+			"Import via modules": "manual/introduction/Import-via-modules",
 			"WebGL compatibility check": "manual/introduction/WebGL-compatibility-check",
 			"How to run things locally": "manual/introduction/How-to-run-thing-locally",
 			"Drawing Lines": "manual/introduction/Drawing-lines",

diff --git a/docs/manual/introduction/Import-via-modules.html b/docs/manual/introduction/Import-via-modules.html
@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<base href="../../" />
+		<script src="list.js"></script>
+		<script src="page.js"></script>
+		<link type="text/css" rel="stylesheet" href="page.css" />
+	</head>
+	<body>
+		<h1>[name]</h1><br />
+
+		<div>
+			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>
+		</div>
+
+		<div>Using a dependency manager like npm avoids these caveats by allowing you to simply download and import your desired version of the libarary onto your machine.</div>
+
+		<h2>Installation via npm</h2>
+
+		<div>Three.js is published as an npm module, see: <a href="https://www.npmjs.com/package/three" target="_blank">npm</a>. This means all you need to do to include three.js into your project is run "npm install three"</div>
+
+		<h2>Importing the module</h2>
+
+		<div>Assuming that you're bundling your files with a tool such as <a href="https://webpack.github.io/" target="_blank">Webpack</a> or <a href="https://github.com/substack/node-browserify" target="_blank">Browserify</a>, which allow you to "require('modules') in the browser by bundling up all of your dependencies."</div>
+
+		<div>
+			You should now be able to import the module into your source files and continue to use it as per normal.
+		</div>
+
+		<code>
+		var THREE = require('three');
+
+		var scene = new THREE.Scene();
+		...
+		</code>
+
+		<div>
+			You're also able to leverage <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import" target="_blank">ES6 import syntax</a>:
+		</div>
+
+		<code>
+		import * as THREE from 'three';
+
+		const scene = new THREE.Scene();
+		...
+		</code>
+
+		<div>
+			or if you wish to import only select parts of three.js library, for example Scene:
+		</div>
+
+		<code>
+		import { Scene } from 'three';
+
+		const scene = new Scene();
+		...
+		</code>
+
+		<h2>Caveats</h2>
+
+		<div>
+			Currenlty it's not possible to import the files within the "examples/js" directroy in this way.
+			This is due to some of the files relying on global namespace pollution of THREE. For more information see <a href="https://github.com/mrdoob/three.js/issues/9562" target="_blank">Transform `examples/js` to support modules #9562</a>.
+		</div>
+	</body>
+</html>