Command Palette

Search for a command to run...

Hectal
Course outline
Topic 0.4Beginner ~21 min · step 4 of 6

Set Up Your Computer

In one line

Install Node.js, open a terminal, create a Vite project called lumen-3d, add three.js 0.186.1, start the dev server and see your cube in the browser. Every command has its real output, and every common failure has a fix.

0/6 · 0%

Think of it like this

The editor on this page is like a rehearsal room the theatre lends you: everything is set up, but you can't take it home. Your own computer is your own workshop: a little setup first, and then it is yours, with your own files, tools and as much space as you need.

Words you'll meet

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

terminal
A window where you type commands instead of clicking: Terminal on macOS and Linux, Windows Terminal or PowerShell on Windows.
Node.js
A program that runs JavaScript on your computer, outside the browser. Tools like Vite are written in JavaScript and need it.
npm
Node's package manager. It downloads libraries (packages) such as three.js into your project's node_modules folder and records them in package.json.
Vite
A dev server and build tool for web projects. npm run dev starts it; it serves your files, understands import, and reloads the page when you save.
dev server
A small web server on your own computer, at an address like http://localhost:5173/, that only you can see while you work.
package.json
The file that lists your project's name, its scripts (dev, build) and the packages it needs, with their versions.

Step by step

01Install Node.js and check it

Go to nodejs.org, download the LTS version (Long-Term Support: the stable one) for your system and install it with the default options. Then open a terminal (see the next step) and type node -v. You should see a version that starts with v24 or higher. npm -v should print a version too (11.x with Node 24).

If the terminal says node or npm is not recognised (Windows) or command not found (macOS, Linux), close the terminal and open a new one: it only learns about new programs when it starts. If it still fails, run the installer again and keep the option that adds Node to the PATH.

terminal
$ node -v
── expected output ──
v24.22.0
Any v24.x (or a newer LTS) is fine. Vite 8 needs Node 20.19 or newer (or 22.12+), and warns you if yours is older.

02Open a terminal in the right place

Windows: press the Windows key, type Terminal, press Enter (Windows Terminal; PowerShell also works). macOS: press Cmd+Space, type Terminal, press Enter. Linux: press Ctrl+Alt+T on most desktops, or find "Terminal" in your apps.

The terminal starts in your home folder. Move to where you keep projects, for example cd Documents (cd means "change directory"). Everything you type next happens in that folder.

03Create the project

Type the command below. It downloads create-vite and makes a folder lumen-3d from the plain-JavaScript template ("vanilla" means no framework). If it asks to install create-vite, answer y.

Then go into the folder and install what the template needs: cd lumen-3d, then npm install. It downloads Vite into node_modules (about 40 packages) and finishes with found 0 vulnerabilities.

terminal
$ npm create vite@latest lumen-3d -- --template vanilla
── expected output ──
> npx
> create-vite lumen-3d --template vanilla
 
│
◇ Scaffolding project in ...\lumen-3d...
│
└ Done. Now run:
 
cd lumen-3d
npm install
npm run dev

04Add three.js, pinned

Still inside lumen-3d, install the exact three.js version this course uses. The --save-exact flag writes "three": "0.186.1" into package.json instead of a range.

terminal
$ npm install --save-exact three@0.186.1
── expected output ──
added 1 package, and audited 42 packages in 5s
 
18 packages are looking for funding
run `npm fund` for details
 
found 0 vulnerabilities
"18 packages are looking for funding" is only an invitation to donate; nothing is wrong.

05Replace the template and start the dev server

Open the lumen-3d folder in your code editor. Delete the template's demo files: src/counter.js, src/style.css, the src/assets folder and public/icons.svg (keep public/favicon.svg). Replace everything in src/main.js with the code of the live example below. The template's index.html already loads only /src/main.js (the old demo's CSS was imported by the main.js you just replaced), so it can stay for now. Topic 0.6 gives you the final index.html.

Then start the dev server with npm run dev and open the address it prints. You should see the turning cube. Leave the terminal open: the server runs until you press Ctrl+C. Every time you save main.js, the page reloads by itself.

terminal
$ npm run dev
── expected output ──
VITE v8.3.4 ready in 482 ms
 
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
The time is different on every machine. Open the Local address in Chrome or Edge.

Try it yourself

  1. 1

    Prove the page reloads by itself

    With the dev server running, change cube.rotation.y = time / 1000; to time / 250 in your own src/main.js and save. The browser reloads without you touching it and the cube spins four times faster. Open the browser's console (F12, then Console): you see three.js 186 is working.

  2. 2

    Look at what you installed

    Open package.json. Under dependencies you see "three": "0.186.1", and under devDependencies you see Vite ("vite": "^8.3.0" in the template when this was written). Open node_modules/three/package.json and find its "version": 0.186.1. The import "three" in your code is answered by this folder.

  3. 3

    Stop and start the server

    Click in the terminal and press Ctrl+C: the server stops, and reloading the browser now shows "This site can't be reached". Run npm run dev again and reload: it is back. This is how you finish work each day and start again the next.

Code & diagrams

The src/main.js you run on your computer New tab

The same file works on this page and in your Vite project. On your computer the import finds three.js in node_modules.

idle

Console

Run the scene to see its console.

Expected console output

three.js 186 is working

Break it on purpose

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

Break #1

Run the dev server in the wrong folder

In a folder that has no package.json (for example the folder above lumen-3d), run npm run dev.

terminal
$ npm run dev
── what you'll see ──
npm error code ENOENT
npm error syscall open
npm error path ...\package.json
npm error errno -4058
npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '...\package.json'
npm error enoent This is related to npm not being able to find a file.
If a folder above has some other package.json, npm finds that one instead and says: npm error Missing script: "dev".

Break #2

Open index.html by double-clicking it

Close the dev server and open lumen-3d/index.html straight from your file browser.

terminal
$ Open the file:// page and look in the console (F12)
── what you'll see ──
Access to script at 'file:///C:/src/main.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: chrome, chrome-untrusted, data, http, https.
Failed to load resource: net::ERR_FAILED
Checked in Chromium. The drive letter is yours, and the list of allowed schemes differs a little between browser versions.

Break #3

Start a second dev server

With one dev server running, open a second terminal in lumen-3d and run npm run dev again.

terminal
$ npm run dev
── what you'll see ──
Port 5173 is in use, trying another one...
 
VITE v8.3.4 ready in 361 ms
 
➜ Local: http://localhost:5174/
Not an error: the second server picks the next free port. If 5174 is taken too, it tries 5175, and so on.

Break #4

Start Vite on an old Node.js

On a computer whose Node.js is older than 20.19 (check with node -v, for example v18.20.4), run npm run dev.

terminal
$ npm run dev
── what you'll see ──
You are using Node.js 18.20.4. Vite requires Node.js version 20.19+ or 22.12+. Please upgrade your Node.js version.
This is the warning text in Vite 8's source (your own version number is shown); it was not run on an old Node for this course. Running `npm install` on that Node also prints an `npm warn EBADENGINE` line naming vite and the Node range it needs.

Myth vs fact

Myth

You need a powerful gaming computer for 3D development.

Fact

Any laptop from the last several years with Chrome or Edge is enough for this course. Phase 17 even teaches you to test on the slowest device you can find.

Myth

npm install three always gives you the same version.

Fact

Without a version it gives you the newest one, which may differ from the course. With @0.186.1 but no --save-exact, package.json allows any newer 0.186.x. Pin exactly to match every example.

Pro corner

Extra depth for experienced readers. New to this? Skip it for now and come back later.

  • ▸

    For three.js, a caret range like ^0.186.1 allows only patch releases (0.186.x), because npm treats a leading 0 as "every minor version may break". --save-exact still matters: it documents the version you tested, and a teammate's npm install gets the same files.

  • ▸

    In production npm run build writes dist/ with hashed file names (index-B2ie5Hn0.js), and Vite warns when one file is over 500 kB. three.js alone crosses that, so Phase 18 splits the 3D code out with import() and loads it only when needed.

  • ▸

    npm run dev -- --host makes the dev server reachable from your phone on the same Wi-Fi (it prints a Network address). Testing on a real phone early saves surprises in Phase 17.

Remember this

  1. 1

    The problem this solves: real projects live in folders on your computer, are built by tools and are put online. The on-page editor is perfect for learning one idea; the showroom you build all course needs a real project you can run, keep and deploy.

  2. 2

    What you install. Node.js (the program that runs JavaScript tools outside the browser; get the LTS version, 24.22.0 on 2026-10-14, from nodejs.org, and its package manager npm comes with it), a code editor (Visual Studio Code is free and common), and Chrome or Edge for the best 3D debugging tools. That is all: Vite and three.js are downloaded into the project by npm.

  3. 3

    Vite. A small tool that serves your project to the browser while you work (the dev server) and packs it into a few files for the web when you are done (npm run build). This course uses Vite 8 (8.3.4 when it was written), which needs Node 20.19+ or 22.12+. The dev server reloads the page when you save a file, and it lets your code write import * as THREE from "three" and find the package in node_modules.

  4. 4

    Pin the version. npm install three@0.186.1 saves "three": "^0.186.1" in package.json, which means "0.186.1 or any newer 0.186.x". npm install --save-exact three@0.186.1 saves "0.186.1" exactly. three.js changes things between releases (it is still at version 0.x), so the course pins it: your project then behaves like every example here.

  5. 5

    Never open index.html by double-clicking it. The browser loads it as a file:// page, and module scripts are blocked there for security: you get a CORS error and a blank page. Always open the address the dev server prints, usually http://localhost:5173/.

Explain it without notes

01

Why do we need a dev server at all? Why not open index.html directly?

02

What is the difference between npm install three@0.186.1 and npm install --save-exact three@0.186.1?

Practice

01

Create the lumen-3d project, pin three.js 0.186.1, replace main.js with the example and get the turning cube on your screen. Write down the exact address your dev server printed.

02

Your friend's terminal says npm error Missing script: "dev". Give two possible causes and how to check each.

Done when you can

  • Install Node.js LTS and check it with node -v

  • Open a terminal on your system and move into a folder with cd

  • Create the lumen-3d Vite project and install three.js 0.186.1 exactly

  • Start the dev server, open its address and see the cube

  • Fix the wrong-folder, file:// and busy-port problems on your own