Build System & Module Exports

This document describes the build pipeline that transforms Three.js source code into various distribution formats, and explains how the library's module exports are configured for different consumption patterns. The build system uses Rollup to bundle source files into ESM and CommonJS formats, with support for multiple rendering backends (WebGL, WebGPU) and various optimization levels.

For information about the core library architecture, see Three.js Overview. For renderer-specific implementations, see Rendering Architecture.

Build Pipeline Overview

The Three.js build system transforms source files located in src/ into multiple distribution formats in the build/ directory. The pipeline handles shader code preprocessing, license header injection, and minification.

100%

Rollup Configuration

The build configuration is defined in utils/build/rollup.config.js1-202 and exports multiple build targets. The configuration uses a functional approach that can be filtered based on command-line arguments.

Build Targets

The configuration defines 7 distinct build targets organized into groups:

Build Target	Input	Output	Format	Minified
Core + WebGPU Nodes	src/Three.Core.js, src/Three.WebGPU.Nodes.js	build/three.core.js, build/three.webgpu.nodes.js	ESM	No
Core + WebGL + WebGPU	src/Three.Core.js, src/Three.js, src/Three.WebGPU.js	build/three.core.js, build/three.module.js, build/three.webgpu.js	ESM	No
TSL	src/Three.TSL.js	build/three.tsl.js	ESM	No
Core + WebGPU Nodes (min)	src/Three.Core.js, src/Three.WebGPU.Nodes.js	build/three.core.min.js, build/three.webgpu.nodes.min.js	ESM	Yes
Core + WebGL + WebGPU (min)	src/Three.Core.js, src/Three.js, src/Three.WebGPU.js	build/three.core.min.js, build/three.module.min.js, build/three.webgpu.min.js	ESM	Yes
TSL (min)	src/Three.TSL.js	build/three.tsl.min.js	ESM	Yes
CommonJS	src/Three.js	build/three.cjs	CJS	No

The build system uses the configOnlyModule flag to optionally limit builds to the first three targets utils/build/rollup.config.js201

Build Plugins

Three custom plugins process the source code during the build:

1. GLSL Plugin

The glsl() plugin processes GLSL shader code embedded in JavaScript files with the .glsl.js extension utils/build/rollup.config.js4-36

Processing steps:

1. Matches files with pattern /\.glsl.js$/
2. Extracts GLSL code from template literals tagged with /* glsl */
3. Strips comments: // single-line and /* */ multi-line
4. Normalizes newlines by collapsing multiple consecutive newlines
5. Converts processed string to JSON format

Example transformation:

// Before
const shader = /* glsl */`
    // This is a comment
    void main() {
        /* block comment */
        gl_FragColor = vec4(1.0);
    }
`;

// After (minified JSON string)
"void main() {n    gl_FragColor = vec4(1.0);n}"

2. Header Plugin

The header() plugin prepends a license header to all output chunks utils/build/rollup.config.js38-61:

/**
 * @license
 * Copyright 2010-2026 Three.js Authors
 * SPDX-License-Identifier: MIT
 */

3. Terser Plugin

The @rollup/plugin-terser plugin minifies code for production builds utils/build/rollup.config.js1 utils/build/rollup.config.js132

Source Entry Points

The build system processes four main entry points that define the library's module structure:

100%

Entry point descriptions:

• src/Three.Core.js: Contains fundamental classes (Vector3, Matrix4, Object3D, BufferGeometry, Material) without renderer implementations
• src/Three.js: Extends core with WebGLRenderer and related subsystems
• src/Three.WebGPU.js: Extends core with WebGPURenderer for modern GPU API
• src/Three.WebGPU.Nodes.js: Includes node-based material system for WebGPU
• src/Three.TSL.js: Provides TSL (Three.js Shading Language) helper functions, depends on three/webgpu as external

Distribution Formats

Three.js is distributed in multiple formats to support different consumption patterns:

ESM (ES Modules)

The primary distribution format for modern JavaScript environments. All ESM files are built with format: 'esm' and use the .js extension.

Core variants:

File	Description	Re-exports Core
build/three.core.js	Core library only (no renderers)	N/A
build/three.module.js	Core + WebGLRenderer	Yes (imports from ./three.core.js)
build/three.webgpu.js	Core + WebGPURenderer	Yes (imports from ./three.core.js)
build/three.webgpu.nodes.js	Core + WebGPU + Node system	Yes (imports from ./three.core.js)
build/three.tsl.js	TSL helper functions	External dep: three/webgpu

The ESM builds use a shared core to avoid duplication. For example, build/three.module.js6 imports and re-exports from ./three.core.js:

import { Matrix3, Vector2, Color, /* ... */ } from './three.core.js';
export { /* ... all core exports ... */ } from './three.core.js';

CommonJS

A single CommonJS bundle for Node.js compatibility:

• build/three.cjs: Complete library including WebGLRenderer in CommonJS format

The CJS build is configured with format: 'cjs' and name: 'THREE' utils/build/rollup.config.js190-196

Sources: utils/build/rollup.config.js184-198 build/three.cjs1-6

Minified Variants

Minified versions are generated for all ESM outputs with the .min.js suffix. These use identical input sources but include the terser plugin:

• build/three.core.min.js
• build/three.module.min.js
• build/three.webgpu.min.js
• build/three.webgpu.nodes.min.js
• build/three.tsl.min.js

Package Export Configuration

The package.json defines how the library is consumed via Node.js module resolution. The configuration uses conditional exports to provide different entry points based on import style.

100%

Export Map Structure

The exports field in package.json8-20 defines the following mappings:

Export Path	Condition	Resolved File
"."	import	./build/three.module.js
"."	require	./build/three.cjs
"./examples/fonts/*"	-	./examples/fonts/*
"./examples/jsm/*"	-	./examples/jsm/*
"./addons"	-	./examples/jsm/Addons.js
"./addons/*"	-	./examples/jsm/*
"./src/*"	-	./src/*
"./webgpu"	-	./build/three.webgpu.js
"./tsl"	-	./build/three.tsl.js

Legacy Entry Points

For backwards compatibility, top-level fields are also defined:

• "main": "./build/three.cjs" - Default Node.js entry (CommonJS) package.json6
• "module": "./build/three.module.js" - ESM-aware bundler entry package.json7
• "type": "module" - Indicates package uses ESM internally package.json5

Build Commands

The build process is invoked via npm scripts defined in package.json45-52:

Command	Script	Description
npm run build	rollup -c utils/build/rollup.config.js	Build all targets
npm run build-module	rollup -c utils/build/rollup.config.js --configOnlyModule	Build only non-minified ESM targets

The --configOnlyModule flag filters the build configuration to produce only the first three build targets (unminified ESM outputs) utils/build/rollup.config.js201

Module Structure

The relationship between source files, build outputs, and package exports creates a layered module system:

100%

This architecture enables:

1. Code sharing: Multiple build outputs import from three.core.js to avoid duplication
2. Selective imports: Consumers can import only WebGL or WebGPU renderers
3. Tree-shaking: ESM format allows bundlers to eliminate unused code
4. Backwards compatibility: CommonJS and legacy module field support older tools