Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
THREE (namespace)
✓ import * as THREE from 'super-three';
✗ const THREE = require('super-three');
`super-three`, like modern `three.js`, primarily uses ES Modules. While `require` might work in some environments, it's not the recommended or tree-shaking friendly approach. Using `* as THREE` imports the entire library namespace.
Named exports (e.g., Scene, WebGLRenderer)
✓ import { Scene, PerspectiveCamera, WebGLRenderer, BoxGeometry, MeshNormalMaterial, Mesh } from 'super-three';
✗ import { WebGLRenderer } from 'super-three/build/super-three.module.js';
For tree-shaking and explicit imports, specific classes and modules should be imported directly from the top-level package. Avoid direct paths into `build/` for core modules as they might change.
Add-ons / Examples (e.g., GLTFLoader)
✓ import { GLTFLoader } from 'super-three/examples/jsm/loaders/GLTFLoader.js';
✗ import { GLTFLoader } from 'super-three/src/loaders/GLTFLoader.js';
Loaders and other community-contributed examples or add-ons are located under `examples/jsm/` and require the full relative path, including the `.js` extension, for correct ES Module resolution.
This quickstart initializes a basic 3D scene with a camera, a rotating cube, and a WebGL renderer, appending the canvas to the document body for animation.
import * as THREE from 'super-three';
const width = window.innerWidth, height = window.innerHeight;
// init
const camera = new THREE.PerspectiveCamera( 70, width / height, 0.01, 10 );
camera.position.z = 1;
const scene = new THREE.Scene();
const geometry = new THREE.BoxGeometry( 0.2, 0.2, 0.2 );
const material = new THREE.MeshNormalMaterial();
const mesh = new THREE.Mesh( geometry, material );
scene.add( mesh );
const renderer = new THREE.WebGLRenderer( { antialias: true } );
renderer.setSize( width, height );
renderer.setAnimationLoop( animate );
document.body.appendChild( renderer.domElement );
// animation
function animate( time ) {
mesh.rotation.x = time / 2000;
mesh.rotation.y = time / 1000;
renderer.render( scene, camera );
}
Debug
Known issues
breakingThis `super-three` package is an abandoned fork based on an older version of `three.js` (0.181.0, last updated ~2 years ago). It will not receive updates, security patches, or new features present in the actively maintained `three.js` library (e.g., 0.183.2+). Using it means missing out on performance improvements, bug fixes, and critical updates, and may introduce compatibility issues with newer ecosystems.fixMigrate to the official `three` package (npmjs.com/package/three) for an actively maintained and up-to-date 3D library. Be aware of potential API changes when migrating from an older `super-three` version to the latest `three.js`.
affects: >=0.181.0
gotcha`three.js` (and thus `super-three`) strongly encourages and primarily ships ES Modules. Importing CommonJS builds or older UMD bundles can lead to larger bundle sizes, broken tree-shaking, and compatibility issues with modern build tools.fixAlways use `import` statements (e.g., `import * as THREE from 'super-three';`) and for loaders/addons, import from `super-three/examples/jsm/...`. Configure your build system (Webpack, Rollup, Vite) to correctly handle ES Modules.
affects: >=0.100.0 (approximate three.js equivalent)
gotcha`three.js` objects like `Geometry`, `Material`, and `Texture` allocate resources on the GPU. If not explicitly disposed of when no longer needed, they can lead to significant memory leaks, especially in single-page applications or long-running experiences. This behavior applies to `super-three` as well.fixCall the `.dispose()` method on `Geometry`, `Material`, and `Texture` instances when they are no longer in use. For materials, iterate through their textures and dispose of each one. Remove objects from the scene to release references.
affects: *
gotchaLoaders (e.g., `GLTFLoader`) and other examples/add-ons are located in `super-three/examples/jsm/`. Incorrect paths or attempting to `require` them can lead to module resolution errors due to differences in module systems or file extensions.fixEnsure you use the exact relative import path, e.g., `import { GLTFLoader } from 'super-three/examples/jsm/loaders/GLTFLoader.js';`. Note the `.js` extension is often required in ES Module environments. affects: *
Errors
Common errors & fixes
Uncaught TypeError: THREE is not defined
Attempting to access `THREE` globally or from a CommonJS `require` call in an environment where it's not exposed, or when using ES Modules without the correct `import * as THREE` statement.
fixFor ES Modules, use `import * as THREE from 'super-three';`. If using CommonJS, `const THREE = require('super-three');` (though ES Modules are the preferred and modern approach). Ensure your build system correctly bundles `super-three`. Failed to resolve module specifier "super-three". Relative references must start with "./", "../", or "/".
A browser environment trying to resolve a bare module specifier (`super-three`) without a module map or import map, or a build system not correctly configured to resolve modules from `node_modules`.
fixEnsure your bundler (Webpack, Rollup, Vite) is correctly configured to resolve `super-three` from `node_modules`. For direct browser use without a bundler, consider using an import map or a CDN version that exposes `THREE` globally.
WebGL: Context Lost
GPU drivers crashing, browser tab being backgrounded for too long, or excessive memory/resource usage leading to the browser discarding the WebGL context.
fixImplement `webglcontextlost` and `webglcontextrestored` event listeners on `renderer.domElement` to gracefully handle context loss and attempt to reinitialize the scene. Optimize resource usage (geometries, textures, shaders) to reduce GPU pressure.
Property 'someProperty' does not exist on type 'Mesh<...>'
TypeScript compiler error indicating an attempt to access a property or method not declared in the `three.js` (or `super-three`) type definitions for the specific object. This often happens when properties are dynamically added, or type casting is missing.
fixEnsure you have `@types/three` installed and that its version is compatible with the `super-three` version (or the `three.js` version it was forked from). Use type assertions (e.g., `(mesh as any).someProperty`) if you are intentionally extending types or adding dynamic properties, or declare custom interfaces to extend `three.js` types properly.
Audit
Dependencies
No dependency data recorded yet.