Web Essentials for 3D Developers

If you come from Unity or Blender, you already think in scenes, components, and assets. The web adds one more layer: a build toolchain that packages everything into something browsers can run. This guide walks you through it — no prior web experience needed.

By the end you'll understand:

• What Node.js and npm are and why you need them
• What package.json and package-lock.json do
• How TypeScript fits in and why it's used
• What Vite does and when you interact with it
• How all of this maps to the familiar Unity/Blender workflow

The web runtime in one sentence

A Needle Engine project compiles your TypeScript components + 3D assets + HTML into a folder of static files that any browser can open — no plugin, no install, just a URL.

Node.js — the engine room

Node.js lets JavaScript run on your machine (outside a browser). Needle Engine uses it at development time to:

• Run the local dev server (npm run dev)
• Compile TypeScript to JavaScript
• Bundle and optimise files for production (npm run build)

Node.js does not run in the final browser build — it's purely a development tool, like Unity's Editor process.

node -v   # e.g. v20.11.0
npm -v    # e.g. 10.2.4

npm — the package manager

npm (Node Package Manager) ships with Node.js. It downloads and manages the libraries your project depends on.

Scaffolding a new project

npm create needle

This is the fastest way to start a standalone Needle Engine project from the terminal — no Unity or Blender required. It asks a few questions (project name, framework) and generates a ready-to-run web project for you:

┌  Welcome to Needle Engine! 🌵
│
◇  Where should we create your project?
│  my-project
│
◇  What framework do you want to use?
│  HTML, CSS, JavaScript with Vite
│
└  Your project is ready!

Next steps:
  1: cd my-project
  2: npm install
  3: npm run dev

The core npm commands

npm install        # Download all dependencies listed in package.json
npm run dev        # Start the local development server
npm run build      # Build production-ready files into dist/

Needle runs these for you automatically when you press Play or click Build in Unity/Blender. You only need to run them manually when working directly in the terminal.

package.json — your project's manifest

Every web project has a package.json at its root. Open it and you'll find:

{
  "name": "my-needle-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "dev-host": "vite --host"
  },
  "dependencies": {
    "@needle-tools/engine": "^4.0.0",
    "three": "^0.160.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  }
}

• scripts — shortcuts for terminal commands. npm run dev runs the "dev" entry.
• dependencies — libraries needed at runtime (Needle Engine, three.js).
• devDependencies — tools needed only during development (TypeScript, Vite).

You rarely edit this by hand. When you add a package via npm install some-library, npm updates it automatically.

package-lock.json

package-lock.json is automatically generated and records the exact version of every installed package (including sub-dependencies). Never edit it manually — but always commit it to git. It ensures every team member and your CI/CD pipeline installs identical versions.

TypeScript — JavaScript with types

Needle Engine components are written in TypeScript (.ts files). TypeScript is JavaScript with optional type annotations — it compiles to plain JavaScript before running in the browser.

Why TypeScript instead of plain JavaScript?

• Errors are caught while you type, not at runtime
• Your editor can autocomplete component properties and methods
• It mirrors C# enough that Unity developers feel at home

// TypeScript — familiar if you know C#
import { Behaviour, serializable } from "@needle-tools/engine";

export class Rotator extends Behaviour {
    @serializable()
    speed: number = 1;

    update() {
        this.gameObject.rotateY(this.speed * this.context.time.deltaTime);
    }
}

You don't need to manually compile TypeScript — Vite handles that automatically when the dev server is running.

Vite — the build tool

Vite is the development server and bundler for Needle Engine projects. Think of it as Unity's background compilation process — it watches your files and rebuilds instantly when something changes.

What Vite does

vite.config.js

The vite.config.js file at the project root configures Vite. Needle adds its own plugin here so the build works out of the box. You usually don't need to touch this file unless you're adding framework integrations (React, Vue, Svelte) or custom build steps.

How it all fits together

Here's the full picture from source to browser:

Your files                   Build tools              Browser
─────────────────────────────────────────────────────────────
src/scripts/*.ts  ──┐
index.html        ──┤  Vite + TypeScript  ──►  dist/  ──►  🌐
assets/*.glb      ──┘  (npm run build)

During development (npm run dev), Vite serves files directly — no dist/ folder needed. The browser connects to the local server and updates live as you edit.

Mapping the web stack to Unity/Blender

Checklist: what you should now understand

• [ ] Node.js runs JavaScript on your machine for development tasks
• [ ] npm installs and manages packages (like Unity's Package Manager or Blender add-ons)
• [ ] package.json lists your dependencies; package-lock.json pins exact versions
• [ ] TypeScript compiles to JavaScript and adds type safety
• [ ] Vite runs the dev server, hot-reloads changes, and bundles for production
• [ ] npm run dev = Play Mode; npm run build = Build

Next steps

• Project Structure — every file and folder explained
• TypeScript Essentials — learn the language
• For Unity Developers — Unity-to-web transition guide
• Create Components — start writing your own scripts