three.js: JavaScript 3D Library for WebGL and WebGPU
What three.js is
three.js is a general-purpose JavaScript 3D library for the web. Its README states the goal as "an easy-to-use, lightweight, cross-browser, general-purpose 3D library" and describes the current scope in one sentence: "The current builds only include WebGL and WebGPU renderers but SVG and CSS3D renderers are also available as addons." It gives developers a scene graph, cameras, lights, geometries, materials, loaders and an animation system, and hides most of the raw GPU API behind those objects.
The project is not a game engine in the sense of an editor-first tool with physics, networking and an asset pipeline built in. The installation guide in the official manual puts it plainly: "Out of the box, three.js includes the fundamentals of a 3D engine." Controls, most file loaders, exporters and post-processing effects live in a separate addons directory that ships in the same npm package, and physics, path tracing, text layout and many other features come from third-party libraries listed on the manual's "Libraries and Plugins" page. The manual's own chapter list shows the range this covers, from responsive scenes, picking and post-processing to voxel geometry, a game tutorial and WebXR, and the plugins page lists higher-level frameworks built on top of three.js, including A-Frame, react-three-fiber, Threlte and Needle Engine.
The repository is mrdoob/three.js, created on 23 March 2010, written in JavaScript and released under the MIT licence; the LICENSE file reads "Copyright © 2010-2026 three.js authors". The npm package is simply called three, and package.json lists mrdoob as author. Development happens on the dev branch rather than main or master, which matters when reading raw files or linking to source.
How it is packaged: builds, entry points and addons
Version numbers
three.js versions are usually referred to as revisions, such as r187. On npm the same release is published as 0.187.0: the minor number is the revision, and the exported REVISION constant is the string "187". Patch releases such as 0.186.1 appear between revisions. Because the major version has stayed at 0, every new revision is a minor bump in semver terms, and a caret range like ^0.187.0 will not pick up r188 automatically. Changes between revisions are tracked on the GitHub releases page and a migration guide on the repository wiki; the README links both.
Entry points
The package is ESM-first. package.json sets "type": "module" and an exports map with these entry points:
three:build/three.module.jsforimport,build/three.cjsforrequire. This is the classic API withWebGLRenderer.three/webgpu:build/three.webgpu.js, the build that containsWebGPURendererand the node material system.three/tsl:build/three.tsl.js, the functions of the three.js Shading Language.three/addons/*andthree/examples/jsm/*: individual addon modules, such asthree/addons/loaders/GLTFLoader.js.three/addons: a single barrel file,examples/jsm/Addons.js, that re-exports the addons.three/src/*: the unbundled source tree.
The installed 0.187.0 package shows the CommonJS entry is now only a shim. build/three.cjs is 631 bytes long: it emits a THREE_CJS_DEPRECATED deprecation warning, says "three is ESM-only going forward", and re-exports the ES module through Node's require(esm) support. Code that still uses require('three') keeps working for now but should move to import.
Addons
The installation guide explains that addons "do not need to be installed separately, but do need to be imported separately". In 0.187.0 the examples/jsm directory holds 510 files across folders such as controls, loaders (57 entries), exporters (Draco, EXR, glTF, KTX2, OBJ, PLY, STL and USDZ), postprocessing, physics, webxr, tsl and inspector. They are versioned together with the core, so an addon always matches the core it was released with.
WebGLRenderer, WebGPURenderer and TSL
three.js currently maintains two renderers, and the documentation is clear about where each stands. The manual's WebGPURenderer page calls it "the next-generation renderer for three.js" and "the modern alternative to the long-standing WebGLRenderer". It uses WebGPU when the browser supports it and "can automatically fall back to using a WebGL 2 backend" when it does not; a forceWebGL: true option forces the fallback for testing. Initialisation is asynchronous, so the manual recommends setAnimationLoop(), which waits for the renderer, or an explicit await renderer.init().
The new renderer comes with a node-based material system and TSL, the three.js Shading Language. According to the manual, TSL lets developers "write shader code with JavaScript in a platform-independent manner", and that code is transpiled to WGSL or GLSL depending on the backend. Post-processing is also new: effects are written in TSL and composed as nodes, with Multiple Render Targets support, and the manual mentions effects such as SSGI, SSS and an improved depth of field that exist only for the new renderer.
The same page lists what does not carry over. Custom materials built on ShaderMaterial or RawShaderMaterial, and changes to built-in materials through onBeforeCompile(), are not supported by WebGPURenderer and must be ported to node materials and TSL. EffectComposer and its passes are not supported either. The manual also says the renderer "is still in an experimental state" and that, depending on the scene, developers may hit missing features or get better performance from WebGLRenderer.
As for WebGLRenderer, the manual says it "is still maintained and the recommended choice for pure WebGL 2 applications", but "there are no plans to add larger new features" because the project's focus is now on WebGPURenderer. The llms.txt file in the repository's docs folder, written as guidance for code generators, gives the same split: WebGLRenderer for "maximum browser compatibility", WebGPURenderer when a project needs TSL, compute shaders or node-based materials.
Key features
- Scene graph. Everything renderable inherits from
Object3D, with parent-child transforms,traverse(), world-matrix updates and JSON serialisation throughtoJSON()andObjectLoader. - Geometry and materials. Built-in primitives (box, sphere, torus knot, extrusions and more),
BufferGeometryfor custom data, and a material set fromMeshBasicMaterialto the physically basedMeshStandardMaterialandMeshPhysicalMaterial. - glTF-first asset workflow. The FAQ calls glTF "the recommended format for importing and exporting assets"; the loading guide lists meshes, materials, textures, skins, skeletons, morph targets, animations, lights and cameras as supported glTF features. Loaders for FBX, OBJ, COLLADA and others are available as addons.
- Math library. Vectors, matrices, quaternions, Euler angles, boxes, spheres, rays, frustums and colour management, all usable without a renderer.
- Picking.
Raycasterreturns sorted intersections with distance, point, face and UV data, used for mouse picking and simple collision queries. - Instancing and batching.
InstancedMeshandBatchedMeshfor drawing many objects with fewer draw calls; the manual has dedicated optimisation chapters. - Animation system. Keyframe tracks, clips, mixers and skeletal animation, documented in the manual's "Animation System" chapter.
- WebXR. VR basics and selection patterns are covered in the manual, and the package keywords include
webxr,virtual-realityandaugmented-reality. - Two renderers, one scene API.
threeandthree/webgpushare the same core module, so scene objects are the same classes whichever renderer draws them (verified below).
Getting started
The manual's installation page recommends npm plus a build tool "for most users", and uses Vite in its examples. Install three.js and Vite in the project folder:
# three.js
npm install --save three
# vite
npm install --save-dev vite
Then start the dev server; the guide says a URL such as http://localhost:5173 appears, and npx vite build produces a deployable dist/ folder later:
npx vite
Addons are imported by path from the same package:
import * as THREE from 'three';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
Without a build tool, the page needs an import map. The repository's llms.txt gives the current form, pinned to the latest release:
<script type="importmap">
{
"imports": {
"three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/"
}
}
</script>
The manual stresses importing every file "from the same version of three.js, and from the same CDN", because mixing sources can duplicate code or break the app. To try the newer renderer, the import changes to the WebGPU build:
import * as THREE from 'three/webgpu';
const renderer = new THREE.WebGPURenderer();
await renderer.init();
A minimal TSL material, from the same file:
import { texture, uv, color } from 'three/tsl';
const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = texture( myTexture ).mul( color( 0xff0000 ) );
Contributors cloning the repository should note the README's warning that the full history "results in a ~2 GB download"; it suggests a shallow clone:
git clone --depth=1 https://github.com/mrdoob/three.js.git
TypeScript types are not bundled. The installation guide points to the community-maintained three-types/three-ts-types project, published on npm as @types/three; its 0.187.0 release appeared on 30 October 2026, the same day as three 0.187.0.
Hands-on: three.js r187 in headless Node.js
three.js is built for browsers, and the manual's FAQ warns that it "depends on browser and DOM APIs that don't always exist in Node.js". A lot of the library is plain JavaScript, though, and tooling such as asset pipelines, test suites and server-side geometry processing often runs three.js without a screen. To see where the line falls, the package was installed and exercised on 17 November 2026 on an Ubuntu 24.04.5 VM (Linux 6.18, x86_64, 2 vCPUs, no GPU, no display) with Node.js 22.23.4 and npm 10.9.9, starting from npm init -y and npm i three.
Install footprint
| Measure | Result |
|---|---|
| Version installed | three 0.187.0 (REVISION "187") |
| Packages added | 1 (no runtime dependencies); npm audit found 0 vulnerabilities |
| Install time, wall clock | about 1.2 s |
| Unpacked size | 21,030,536 bytes (du -sb), shown as 24 MB by du -sh; matches the registry's unpackedSize |
| Files in package | 1,277 (registry fileCount agrees) |
build/ | 6 files, 6.7 MB: three.core.js (1.47 MB), three.module.js (659 KB), three.webgpu.js (1.35 MB), three.webgpu.nodes.js (2.39 MB), three.tsl.js (1.07 MB), three.cjs (631 bytes) |
examples/jsm/ (addons) | 510 files, 11 MB |
src/ | 758 files, 6.5 MB |
Cold node -e "import('three')", whole process | 57-60 ms over three runs |
No minified builds are in the package; minification is left to the application's bundler. Most of the install size is addons and source, which a bundler only includes when imported.
Entry points in Node
| Import | Observed |
|---|---|
import * as THREE from 'three' | 443 exported names |
import('three/webgpu') | 637 names, includes WebGPURenderer and MeshStandardNodeMaterial; does not export WebGLRenderer |
import('three/tsl') | 819 names |
| Class identity across entries | Mesh and Vector3 from three and three/webgpu are the same objects (both builds import three.core.js) |
require('three') | Works, 443 names, prints DeprecationWarning: `require("three")` is deprecated and will be removed. |
import('three/addons') (barrel) | Fails: Only URLs with a scheme in: file and data are supported by the default ESM loader. Received protocol 'https:' |
| Individual addon imports | GLTFExporter.js and GLTFLoader.js import fine |
The barrel failure has a specific cause: Addons.js re-exports loaders/TTFLoader.js, which imports opentype.js straight from https://cdn.jsdelivr.net, and libs/demuxer_mp4.js does the same for mp4box. Browsers accept URL imports; Node's default loader does not, and a bundler may also need configuration for them. Importing addons by individual path avoids the problem.
Scene graph and math without a renderer
The test built a Scene containing a Group with one Mesh made from BoxGeometry(2, 1, 1) and MeshStandardMaterial, plus a DirectionalLight. The group was moved to x = 10; the mesh was offset to y = 2, rotated 90 degrees around Y and scaled by 2 on Y; then scene.updateMatrixWorld(true) ran.
| Operation | Output |
|---|---|
| Box geometry | 24 vertices, 36 indices (12 triangles), 6 material groups |
computeBoundingBox() (local) | min (-1, -0.5, -0.5), max (1, 0.5, 0.5) |
computeBoundingSphere() (local) | radius 1.2247 |
mesh.matrixWorld.elements (column-major) | [0, 0, -1, 0, 0, 2, 0, 0, 1, 0, 0, 0, 10, 2, 0, 1] |
getWorldPosition() | (10, 2, 0) |
Box3.setFromObject(mesh) (world) | min (9.5, 1, -1), max (10.5, 3, 1) |
| Sphere around that world box | centre (10, 2, 0), radius 1.5 |
| Mesh quaternion | (0, 0.7071, 0, 0.7071) |
Vector3(1, 1, 0).project(camera), 70° FOV, 16:9, camera at z = 5 | NDC (0.1607, 0.2856, 0.962) |
scene.toJSON() then ObjectLoader.parse() | 3,314 bytes of JSON; parsed scene had 2 children and the mesh came back as Mesh |
The matrix shows the transforms composing as expected: the rotation swaps the X and Z axes, the scale doubles the Y column, and the translation column holds the group offset plus the mesh offset. The world bounding box reflects the rotation, since the box's 2-unit length now runs along Z.
Raycasting
| Ray | Result |
|---|---|
Origin (10, 2, 10), direction (0, 0, -1), intersectObjects(scene.children, true) | 1 hit on box: distance 9, point (10, 2, 1), faceIndex 2, face.normal (-1, 0, 0); the call took 1.4 ms (first call, including warm-up) |
| Origin (0, 0, 10), same direction | 0 hits |
One detail worth knowing: the reported hit point is in world space, but face.normal is in the object's local space. The ray struck the box's local -X face, which the 90-degree rotation turned to face world +Z. Code that needs a world normal has to transform it with the object's normal matrix.
glTF export and import
| Step | Result |
|---|---|
| Globals in Node 22 | Blob and TextEncoder present; FileReader undefined |
GLTFExporter.parseAsync(scene, { binary: true }), no shim | Fails: ReferenceError: FileReader is not defined |
Same with binary: false, no shim | Fails with the same error, because buffers are embedded as data URIs through FileReader |
Binary export with a 5-line FileReader shim | 2,076-byte ArrayBuffer in 4.4 ms; header magic glTF, version 2, JSON chunk 1,208 bytes, BIN chunk 840 bytes |
| JSON export with the shim | 2,373 bytes; one buffer as data:application/octet-stream;base64,…; generator string THREE.GLTFExporter r187 |
GLTFLoader.parseAsync() on the GLB, in a fresh process without the shim | Works: one Mesh with MeshStandardMaterial, colour 3366ff, roughness 0.5, position (0, 2, 0), scale (1, 2, 1), quaternion (0, 0.7071, 0, 0.7071), 24 vertices with position, normal and uv |
The shim, loaded with node --import, defined a global FileReader class with readAsArrayBuffer and readAsDataURL, each built on Blob.arrayBuffer() and calling onloadend; those are the only FileReader calls in GLTFExporter.js. That is enough for geometry and materials. Textures are a different matter: the exporter draws images through OffscreenCanvas or document.createElement('canvas'), neither of which Node provides, so exporting textured scenes in Node would need more than this shim.
Renderers in Node
| Attempt | Result |
|---|---|
typeof THREE.WebGLRenderer | function; importing it is fine |
new THREE.WebGLRenderer() | ReferenceError: document is not defined |
new WebGLRenderer({ canvas }) with a stub canvas whose getContext() returns null | Error: THREE.WebGLRenderer: Error creating WebGL context. |
new WebGPURenderer() from three/webgpu | ReferenceError: document is not defined |
navigator.gpu in Node 22 | navigator exists, navigator.gpu is undefined |
So everything up to the renderer runs in plain Node: building scenes, math, raycasting, JSON serialisation, glTF parsing, and glTF export with a small shim. Rendering needs a real or emulated GPU context. The FAQ mentions headless-gl and jsdom-global as shims some projects use; those were not tested here.
How three.js compares
The table sets three.js against two other open-source web 3D engines, a framework built on top of it, a React renderer for it, and writing against the browser APIs directly. Facts come from each project's README and its npm registry entry as fetched on 17 November 2026; none of these were benchmarked here.
| Option | What its README says it is | Rendering | Latest on npm | Licence (npm) | Relationship to three.js |
|---|---|---|---|---|---|
| three.js | "JavaScript 3D library" | WebGLRenderer; WebGPURenderer with WebGL 2 fallback | 0.187.0 (30 Oct 2026) | MIT | - |
| Babylon.js | Engine with an online playground; README says its npm packages ship "with full typing support" | Not stated in the README sections read | @babylonjs/core 9.37.0 (16 Nov 2026) | Apache-2.0 | Independent engine |
| PlayCanvas Engine | "open-source web graphics engine built on WebGPU and WebGL2" for 2D and 3D apps and games | WebGPU preferred, WebGL2 fallback in its hello-world | playcanvas 2.24.1 (12 Nov 2026) | MIT | Independent engine with entity-component design |
| A-Frame | "A web framework for building browser based 3D, AR and VR experiences", declarative HTML | Through three.js | aframe 1.8.0 (23 Jun 2026) | MIT | Built on three.js; its 1.8.0 package depends on [email protected], aliased as three |
| react-three-fiber | "a React renderer for threejs" | Through three.js | @react-three/fiber 9.8.2 (14 Oct 2026) | MIT | Peer-depends on three >=0.156 and React 19 |
| Raw WebGL / WebGPU | Browser APIs, no library | Whatever the code implements | - | - | Full control, no scene graph, loaders or materials |
The practical split: three.js is a library that leaves structure to the application, while Babylon.js and PlayCanvas present themselves as fuller engines with their own tooling, playground or editor ecosystem. A-Frame and react-three-fiber are not really alternatives so much as ways to use three.js through HTML elements or React components; A-Frame pins a separately published super-three package in place of three, so mixing it with a separately installed three needs care. react-three-fiber's README claims "no overhead" relative to plain three.js because components render outside React; that is the project's claim, not a measured result. Writing raw WebGL or WebGPU makes sense when the scene is small and fixed, or when the goal is learning the API itself. For a specific technique, such as Gaussian splat rendering, purpose-built renderers on top of three.js exist, for example Spark.
Limits and when not to use it
- It is a library, not an engine. There is no built-in physics, editor-driven workflow or networking. The manual sends physics to libraries such as Rapier, cannon-es, ammo.js and Jolt. Projects that need serious physics simulation, such as robotics work in MuJoCo, generally use three.js only as a viewer.
- Breaking changes arrive as minor versions. With the version stuck at 0.x, each revision can change APIs, and the README links a migration guide for that reason. Pin exact versions and read release notes before upgrading.
- Renderer transition costs. Custom
ShaderMaterialcode,onBeforeCompile()patches andEffectComposerchains do not run underWebGPURenderer, and the manual still calls that renderer experimental. MeanwhileWebGLRendererwill not get larger new features. Large codebases face a port at some point. - Manual resource cleanup. The disposal guide says geometries, materials, textures and render targets "are not released automatically"; applications must call
dispose()on each, and disposing a material does not free its textures. - No input validation. The FAQ states that "for performance reasons, three.js doesn't validate inputs in most cases", so bad values produce odd results rather than errors.
- Node support is partial. The tests above show which parts work headless. The
three/addonsbarrel fails in Node because of CDN URL imports,GLTFExporterneeds aFileReadershim, and rendering needs a GPU context. - Types are separate. TypeScript definitions come from the community
@types/threepackage, which tracks releases but is a second dependency to keep in step. - Wrong tool for 2D maps or plain charts. For tiled 2D web maps a dedicated library like Leaflet is simpler; three.js pays off when the data really needs a third dimension.
- Desktop packaging is out of scope. three.js renders in a browser context; shipping a desktop app means wrapping the web front end with something like Tauri, where WebGL and WebGPU availability depend on the platform's webview.
Release cadence and documentation notes
The npm registry lists 315 published versions since the package was created on 7 December 2012. Recent revisions landed on 31 October 2025 (r181), 10 December 2025 (r182), 18 February 2026 (r183), 16 April 2026 (r184), 25 June 2026 (r185), 8 September 2026 (r186) and 30 October 2026 (r187), with patch releases 0.183.1, 0.183.2, 0.185.1 and 0.186.1 in between. That is roughly one revision every one to two and a half months over the past year, a slower rhythm than in late 2024 and 2025, when r170 to r175 took about five months and r175 to r180 a little over five.
A few documentation details came up while reading the sources. The manual's import-map example still uses v0.149.0 as the sample version, while llms.txt pins 0.187.0, so copy the version from npm rather than the manual. Manual pages now live under manual/pages/ in the repository with language-neutral URLs, and older language-prefixed links such as #en/installation are redirected by the manual's index page. The migration guide is on the GitHub wiki rather than in the repository, so it is not part of a source checkout.
Project activity
Checked 17 November 2026: latest release r187 / three 0.187.0 (published to npm on 30 October 2026), MIT licence, about 118,700 stars on the mrdoob/three.js repository (118,732 at the time of writing), with about 37,000 forks and a push on the day of checking. The project is written in JavaScript, was created on 23 March 2010 and develops on the dev branch. Examples, documentation and the manual are published at threejs.org; questions go to the forum, Stack Overflow's three.js tag and the project Discord, all linked from the README.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.
Repository:https://github.com/mrdoob/three.js
GitHub - mrdoob/three.js: three.js: JavaScript 3D Library for WebGL and WebGPU
three.js is the MIT-licensed JavaScript 3D library for the web, with WebGL and WebGPU renderers. r187 (npm 0.187.0) tested in headless Node: scene math, raycast...
github - mrdoob/three.js
Related Projects
FastAPI: Python Web Framework for Building APIs
Python API framework using type hints for validation, dependency injection and OpenAPI docs.
Uptime Kuma: Self-Hosted Uptime Monitoring Tool
Self-hosted uptime monitor with 90+ notification services, status pages and a WebSocket-driven web dashboard.
Hugo: Fast Static Site Generator Written in Go
Single-binary Go static site generator with built-in asset pipelines, live dev server and Hugo Modules.
Maintain three.js: JavaScript 3D Library for WebGL and WebGPU? Add the badge to your README
Show that the project is featured on TechLogHub and send readers to this write-up.
[](https://techloghub.com/open-source/three-js?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)