headless-three

Headless Three.js rendering for Node.js, made simple. Render 3D scenes to images on the server with no browser required. Runs Three.js r162 (the last version with WebGL 1 support) without polluting the global scope.

Features

• Three.js r162 running in an isolated VM context
• No global scope pollution
• Works with any canvas library (skia-canvas, @napi-rs/canvas, canvas)
• Headless WebGL rendering via gl
• Built-in render function with multi-format output (PNG, JPEG, WebP, etc.) via sharp
• Texture loading utility
• Extensible via runInContext for custom loaders

Install

npm install headless-three

You also need a canvas library:

npm install skia-canvas
# or
npm install @napi-rs/canvas
# or
npm install canvas

Quick Start

import { Canvas, Image, ImageData } from "skia-canvas"
import getTHREE from "headless-three"

const { THREE, render, loadTexture } = await getTHREE({ Canvas, Image, ImageData })

// Create scene
const scene = new THREE.Scene()
const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 100)
camera.position.set(0, 0, 5)

// Add a lit cube
scene.add(new THREE.AmbientLight(0x404040))
const light = new THREE.DirectionalLight(0xffffff, 1)
light.position.set(-1, 2, 3)
scene.add(light)

// Load a texture
const texture = await loadTexture("path/to/texture.png")

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(1, 1, 1),
  new THREE.MeshStandardMaterial({ map: texture })
)
scene.add(cube)

// Render to file
await render({
  scene,
  camera,
  width: 512,
  height: 512,
  path: "output.png"
})

// Or get a PNG buffer
const buffer = await render({ scene, camera })

API

getTHREE(options)

Returns a promise that resolves to { THREE, render, loadTexture, runInContext, parseColor }.

Options

Returns

All helpers (render, loadTexture, runInContext, parseColor) are also attached to the returned THREE object under THREE.headless, so you can destructure just THREE and access them as THREE.headless.render(...) etc.

render(options)

Renders a scene to an image buffer or file. When saving to a file, the format is inferred from the extension unless format is specified. Buffer output defaults to PNG.

// Save to file (format inferred from extension)
await render({
  scene,
  camera,
  width: 512,
  height: 512,
  path: "output.png"
})

// Save as JPEG
await render({ scene, camera, path: "output.jpg" })

// Force format regardless of extension
await render({ scene, camera, path: "output.img", format: "webp" })

// Get PNG buffer (default)
const buffer = await render({ scene, camera })

// Get JPEG buffer
const buffer = await render({ scene, camera, format: "jpeg" })

// Smaller JPEG via mozjpeg encoder
await render({
  scene,
  camera,
  path: "output.jpg",
  output: { quality: 85, mozjpeg: true }
})

// Maximum PNG compression
await render({
  scene,
  camera,
  path: "output.png",
  output: { compressionLevel: 9, effort: 10 }
})

loadTexture(input)

Creates a THREE.CanvasTexture from various input types:

// From a file path
const texture = await loadTexture("path/to/image.png")

// From an Image
const img = new Image()
img.src = "path/to/image.png"
const texture = await loadTexture(img)

// From a Canvas
const texture = await loadTexture(canvas)

runInContext(code)

Executes code inside the same VM context as Three.js. This is useful for loading bundled Three.js addons:

import fs from "node:fs"

const { THREE, runInContext } = await getTHREE({ ... })

// Load a pre-bundled addon
runInContext(fs.readFileSync("GLTFLoader.bundle.js", "utf-8"))

parseColor(input)

render()'s background option accepts many color formats (hex, arrays, objects, CSS strings, etc.). parseColor exposes the same parser so you can accept those formats in your own code without duplicating the logic.

Returns { color, alpha }, where color is a THREE.Color and alpha is a number in [0, 1].

const { THREE, parseColor } = await getTHREE({ ... })

const { color, alpha } = parseColor("rgba(255, 0, 0, 0.5)")
renderer.setClearColor(color, alpha)

Supported formats

Alpha defaults to fully opaque when not specified.

All non-THREE.Color inputs are treated as sRGB values and decoded to linear via THREE.Color().setRGB(..., SRGBColorSpace) so the output matches the color you'd pick in a color picker.

How It Works

headless-three uses Node.js's vm module to create an isolated V8 context with polyfilled browser APIs (document, window, URL, etc.). Three.js's CJS build runs inside this sandbox, thinking it's in a browser. The canvas library you provide handles the actual drawing surface and image operations. Rendering uses gl for headless WebGL and sharp for image encoding.

License

MIT © Ewan Howell