-
-
Notifications
You must be signed in to change notification settings - Fork 35.7k
/
Copy pathinstallation.html
306 lines (253 loc) · 13.9 KB
/
installation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
<!DOCTYPE html><html lang="en"><head>
<meta charset="utf-8">
<title>Installation</title>
<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@threejs">
<meta name="twitter:title" content="Three.js – Installation">
<meta property="og:image" content="https://threejs.org/files/share.png">
<link rel="shortcut icon" href="../../files/favicon_white.ico" media="(prefers-color-scheme: dark)">
<link rel="shortcut icon" href="../../files/favicon.ico" media="(prefers-color-scheme: light)">
<link rel="stylesheet" href="../resources/lesson.css">
<link rel="stylesheet" href="../resources/lang.css">
<script type="importmap">
{
"imports": {
"three": "../../build/three.module.js"
}
}
</script>
</head>
<body>
<div class="container">
<div class="lesson-title">
<h1>Installation</h1>
</div>
<div class="lesson">
<div class="lesson-main">
<h2>Project structure</h2>
<p>
Every three.js project needs at least one HTML file to define the webpage, and a JavaScript file to run your three.js code. The structure and naming choices below aren't required, but will be used throughout this guide for consistency.
</p>
<ul>
<li>
<i>index.html</i>
<pre class="prettyprint notranslate lang-js" translate="no">
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My first three.js app</title>
<style>
body { margin: 0; }
</style>
</head>
<body>
<script type="module" src="/main.js"></script>
</body>
</html>
</pre>
</li>
<li>
<i>main.js</i>
<pre class="prettyprint notranslate lang-js" translate="no">
import * as THREE from 'three';
...
</pre>
</li>
<li>
<i>public/</i>
<ul>
<li>
The <i>public/</i> folder is sometimes also called a "static" folder, because the files it contains are pushed to the website unchanged. Usually textures, audio, and 3D models will go here.
</li>
</ul>
</li>
</ul>
<p>
Now that we've set up the basic project structure, we need a way to run the project locally and access it through a web browser. Installation and local development can be accomplished with npm and a build tool, or by importing three.js from a CDN. Both options are explained in the sections below.
</p>
<h2>Option 1: Install with NPM and a build tool</h2>
<h3>Development</h3>
<p>
Installing from the [link:https://www.npmjs.com/ npm package registry] and using a [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC build tool] is the recommended approach for most users — the more dependencies your project needs, the more likely you are to run into problems that the static hosting cannot easily resolve. With a build tool, importing local JavaScript files and npm packages should work out of the box, without import maps.
</p>
<ol>
<li>
Install [link:https://nodejs.org/ Node.js]. We'll need it to load manage dependencies and to run our build tool.
</li>
<li>
<p>
Install three.js and a build tool, [link:https://vitejs.dev/ Vite], using a [link:https://www.joshwcomeau.com/javascript/terminal-for-js-devs/ terminal] in your project folder. Vite will be used during development, but it isn't part of the final webpage. If you prefer to use another build tool, that's fine — we support modern build tools that can import [link:https://eloquentjavascript.net/10_modules.html#h_zWTXAU93DC ES Modules].
</p>
<pre class="prettyprint notranslate" translate="no">
# three.js
npm install --save three
# vite
npm install --save-dev vite
</pre>
<aside>
<details>
<summary>Installation added <i>node_modules/</i> and <i>package.json</i> to my project. What are they?</summary>
<p>
npm uses <i>package.json</i> to describe which versions of each dependency you've installed. If you have other people working on the project with you, they can install the original versions of each dependency simply by running <i>npm install</i>. If you're using version history, commit <i>package.json</i>.
</p>
<p>
npm installs the code for each dependency in a new <i>node_modules/</i> folder. When Vite builds your application, it sees imports for 'three' and pulls three.js files automatically from this folder. The <i>node_modules/</i> folder is used only during development, and shouldn't be uploaded to your web hosting provider or committed to version history.
</p>
</details>
<details>
<summary>Improve your editor auto-completion with <i>jsconfig</i> or <i>tsconfig</i></summary>
<p>
Place a <i>jsconfig.json</i> (or <i>tsconfig.json</i> for TypeScript projects) in your project's root. Adding the configuration below helps your editor locate three.js files for enhanced auto-completion.
</p>
<pre class="prettyprint notranslate lang-js" translate="no">
{
"compilerOptions": {
// other options...
"paths": {
"three/webgpu": ["node_modules/three/build/three.webgpu.js"],
"three/tsl": ["node_modules/three/build/three.tsl.js"],
},
}
}
</pre>
</details>
</aside>
</li>
<li>
From your terminal, run:
<pre class="prettyprint notranslate" translate="no">npx vite </pre>
<aside>
<details>
<summary>What is <i>npx</i>?</summary>
<p>
npx is installed with Node.js, and runs command line programs like Vite so that you don't have to search for the right file in <i>node_modules/</i> yourself. If you prefer, you can put [link:https://vitejs.dev/guide/#command-line-interface Vite's common commands] into the [link:https://docs.npmjs.com/cli/v9/using-npm/scripts package.json:scripts] list, and use <i>npm run dev</i> instead.
</p>
</details>
</aside>
</li>
<li>
If everything went well, you'll see a URL like <i>http://localhost:5173</i> appear in your terminal, and can open that URL to see your web application.
</li>
</ol>
<p>
The page will be blank — you're ready to <a href="creating-a-scene.html">create a scene</a>.
</p>
<p>
If you want to learn more about these tools before you continue, see:
</p>
<ul>
<li>
[link:https://threejs-journey.com/lessons/local-server three.js journey: Local Server]
</li>
<li>
[link:https://vitejs.dev/guide/cli.html Vite: Command Line Interface]
</li>
<li>
[link:https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Understanding_client-side_tools/Package_management MDN: Package management basics]
</li>
</ul>
<h3>Production</h3>
<p>
Later, when you're ready to deploy your web application, you'll just need to tell Vite to run a production build — <i>npx vite build</i>. Everything used by the application will be compiled, optimized, and copied into the <i>dist/</i> folder. The contents of that folder are ready to be hosted on your website.
</p>
<h2>Option 2: Import from a CDN</h2>
<h3>Development</h3>
<p>Installing without build tools will require some changes to the project structure given above.</p>
<ol>
<li>
<p>
We imported code from 'three' (an npm package) in <i>main.js</i>, and web browsers don't know what that means. In <i>index.html</i> we'll need to add an [link:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap import map] defining where to get the package. Put the code below inside the <i><head></head></i> tag, after the styles.
</p>
<pre class="prettyprint notranslate lang-js" translate="no">
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/"
}
}
</script>
</pre>
<p>
Don't forget to replace <i><version></i> with an actual version of three.js, like <i>"v0.149.0"</i>. The most recent version can be found on the [link:https://www.npmjs.com/package/three?activeTab=versions npm version list].
</p>
</li>
<li>
<p>
We'll also need to run a <i>local server</i> to host these files at URL where the web browser can access them. While it's technically possible to double-click an HTML file and open it in your browser, important features that we'll later implement, do not work when the page is opened this way, for security reasons.
</p>
<p>
Install [link:https://nodejs.org/ Node.js], then run [link:https://www.npmjs.com/package/serve serve] to start a local server in the project's directory:
</p>
<pre class="prettyprint notranslate" translate="no">npx serve .</pre>
</li>
<li>
If everything went well, you'll see a URL like http://localhost:3000 appear in your terminal, and can open that URL to see your web application.
</li>
</ol>
<p>
The page will be blank — you're ready to [link:#manual/introduction/Creating-a-scene create a scene].
</p>
<p>
Many other local static servers are available — some use different languages instead of Node.js, and others are desktop applications. They all work basically the same way, and we've provided a few alternatives below.
</p>
<details>
<summary>More local servers</summary>
<h3>Command Line</h3>
<p>Command line local servers run from a terminal window. The associated programming language may need to be installed first.</p>
<ul>
<li><i>npx http-server</i> (Node.js)</li>
<li><i>npx five-server</i> (Node.js)</li>
<li><i>python -m SimpleHTTPServer</i> (Python 2.x)</li>
<li><i>python -m http.server</i> (Python 3.x)</li>
<li><i>php -S localhost:8000</i> (PHP 5.4+)</li>
</ul>
<h3>GUI</h3>
<p>GUI local servers run as an application window on your computer, and may have a user interface.</p>
<ul>
<li>[link:https://greggman.github.io/servez Servez]</li>
</ul>
<h3>Code Editor Plugins</h3>
<p>Some code editors have plugins that spawn a simple server on demand.</p>
<ul>
<li>[link:https://marketplace.visualstudio.com/items?itemName=yandeu.five-server Five Server] for Visual Studio Code</li>
<li>[link:https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer Live Server] for Visual Studio Code</li>
<li>[link:https://atom.io/packages/atom-live-server Live Server] for Atom</li>
</ul>
</details>
<h3>Production</h3>
<p>
When you're ready to deploy your web application, push the source files to your web hosting provider — no need to build or compile anything. The downside of that tradeoff is that you'll need to be careful to keep the import map updated with any dependencies (and dependencies of dependencies!) that your application requires. If the CDN hosting your dependencies goes down temporarily, your website will stop working too.
</p>
<p>
<i><b>IMPORTANT:</b> Import all dependencies from the same version of three.js, and from the same CDN. Mixing files from different sources may cause duplicate code to be included, or even break the application in unexpected ways.</i>
</p>
<h2>Addons</h2>
<p>
Out of the box, three.js includes the fundamentals of a 3D engine. Other three.js components — such as controls, loaders, and post-processing effects — are part of the [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm addons/] directory. Addons do not need to be <i>installed</i> separately, but do need to be <i>imported</i> separately.
</p>
<p>
The example below shows how to import three.js with the `OrbitControls` and `GLTFLoader` addons. Where necessary, this will also be mentioned in each addon's documentation or examples.
</p>
<pre class="prettyprint notranslate lang-js" translate="no">
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const controls = new OrbitControls( camera, renderer.domElement );
const loader = new GLTFLoader();
</pre>
<p>
Some excellent third-party projects are available for three.js, too. These need to be installed separately — see <a href="libraries-and-plugins">Libraries and Plugins</a>.
</p>
<h2>Next Steps</h2>
<p>
You're now ready to <a href="creating-a-scene.html">create a scene</a>.
</p>
</div>
</div>
</div>
<script src="../resources/prettify.js"></script>
<script src="../resources/lesson.js"></script>
</body></html>