build

This document explains the build system, package manager, and tooling architecture for @react-three/fiber.

We use pnpm for its performance, strict dependency resolution, and first-class monorepo support.

Configuration: pnpm-workspace.yaml

We use Unbuild for building all packages.

Configuration: packages/fiber/build.config.ts

three and three/webgpu are separate bundles that share a core: three.module.js is three.core.js plus the WebGL renderer, three.webgpu.js is three.core.js plus the WebGPU renderer and the node system. There is no import that gives you the core alone, and a bundler assigns a module to one chunk: if fiber's core statically imported either bundle, that bundle -- renderer included -- would land in every app's eager graph, whichever renderer the app used. Size-sensitive apps have (loudly) objected to exactly that.

So the four entry points are built in one rollup run and fiber's core has no static import from three or three/webgpu. Everything the entries share (the reconciler, the store, events, hooks, <Environment>) is emitted once as dist/shared/fiber.<hash>.mjs, and each entry is a few kilobytes of glue that imports it.

Each renderer is described by a support module, the only two modules in fiber that import three:

The shapes are in types/provider.d.ts. An entry hands createRoot/Canvas a provider, a loader per renderer it can construct:

// src/index.tsx -- both, each downloaded when a root first asks for it
const provider: RendererProvider = {
  webgl: () => import('./support/webgl').then((m) => m.webglSupport),
  webgpu: () => import('./support/webgpu').then((m) => m.webgpuSupport),
}

// src/legacy.tsx -- one, already loaded
const provider: RendererProvider = { webgl: () => webglSupport }

configure() picks the renderer the entry's provider offers (WebGPU on the root entry and /webgpu, WebGL on /legacy), awaits its support, and keeps it as state.internal.support. That is the moment three is downloaded on the root entry: bundlers emit dist/chunks/webgpu.mjs as a lazy chunk. /legacy and /webgpu import their support statically, for apps that would rather not have that request; they are the same core.

A separate file is useful when it isolates behavior or protects a dependency boundary. It does not necessarily introduce another domain. Independent semantic tests support a boundary; the boundary should also reduce what a maintainer must understand to change that behavior.

Within root management, the root sequences renderer initialization, synchronous configuration, scheduler registration, and extension setup before resolving readiness. Configuration decides which inputs changed and resolves requested dimensions. The store accepts configured dimensions only while sizing remains automatic; public setSize() takes or releases imperative ownership. Both paths update size and viewport through the same store operation, so subscribers never observe temporary ownership changes. Camera and renderer resizing remain store effects.

context.ts and three.ts are infrastructure modules: they isolate the lightweight extension entry and lazy renderer loading. They are not separate application domains. Promise helpers live in utils/promise.ts; React helpers, including useGate, live in utils/react.tsx. web/Canvas.tsx adapts DOM and React to the root API.

Activity connectivity does not own renderer lifetime: final root removal releases resources after accepted configuration and React cleanup finish. Portals reconnect their injected scene on reveal; the reconciler owns disposal of their children.

Nothing in src/core/ knows which renderer it will run with, and nothing there imports a three value:

// In src/core/: types are free, values are not
import type { Scene, Vector3 } from 'three'
import type { WebGPURenderer } from 'three/webgpu'

const scene = new (getThree().Scene)() // shared core
const fbo = new support.CubeRenderTarget(size) // renderer-specific, from the root's support
const { Node } = support.occlusion // WebGPU only

A library that imports anything except Canvas or createRoot from @react-three/fiber adds no renderer to an app, on any entry, and no second copy of core. @react-three/fiber/extension remains the stable, smallest surface for packages that build on fiber (@react-three/tsl uses it). pnpm verify-treeshake builds such consumers with Vite and esbuild and asserts all of it on the output; see TESTING.md.

ThreeElementsOf<T> (types/three.d.ts) derives a JSX map from a three namespace. Each entry declares its own ThreeElements from it and augments react's IntrinsicElements at the bottom of its file: the root entry from typeof import('three') & typeof import('three/webgpu'), /legacy from three only, /webgpu from three/webgpu only. So /legacy never advertises a <meshBasicNodeMaterial> it cannot build, and the shared declaration chunk carries no augmentation at all. import type { ReactThreeFiber } from '@react-three/fiber/legacy' gives that entry's namespace (types/entries/*.d.ts).

unbuild --stub creates lightweight stubs that redirect to source:

// dist/index.mjs (stub)
import * as module from '../src/index.tsx'
export * from '../src/index.tsx'
export default module.default

Code changes reflect immediately without rebuilding.

packages/fiber/dist/
├── index.{mjs,cjs}          # Default entry: glue + lazy provider
├── legacy.{mjs,cjs}         # Legacy entry: glue + static WebGL support
├── webgpu/
│   └── index.{mjs,cjs}      # WebGPU entry: glue + static WebGPU support
├── extension.{mjs,cjs}      # Three-free surface for libraries
├── chunks/
│   ├── webgl.{mjs,cjs}      # WebGL support: the one module importing `three`
│   └── webgpu.{mjs,cjs}     # WebGPU support: the one module importing `three/webgpu` + `three/tsl`
└── shared/
    └── fiber.<hash>.{mjs,cjs}  # Core, imported by every entry

Both pnpm verify-treeshake and pnpm verify-types run against this output; pnpm run ci and CI run them right after the build.

To add a specialized bundle (e.g., a new rendering backend):

@react-three/tsl is in scripts/release.js and .github/workflows/canary.yml. The canary publishes with npm trusted publishing (OIDC, no token), which can only be configured for a package that already exists on npm, so the very first version is published by hand, as a canary, before the change that adds tsl to the canary workflow is merged. Otherwise the first canary run after that merge fails at tsl, after fiber and test-renderer have already published.

tsl's peer range, ^10.0.0-alpha.6, accepts every fiber canary and every release after 10.0.0-alpha.5, the last version without the @react-three/fiber/extension entry tsl needs.

To check the package as npm will see it without publishing: cd packages/tsl && pnpm pack, then install the tarball (next to a packed fiber) into a fresh app.

Vitest provides faster native ESM testing with better React 19 compatibility.

pnpm's strictness and efficiency make it preferred for modern React monorepos.

Preconstruct couldn't support per-entry alias resolution for our THREE.js import strategy.