super-three: JavaScript 3D Library (Abandoned Fork)

Common errors

• Uncaught TypeError: THREE is not defined

  cause 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.
  fix For 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 "/".

  cause 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`.
  fix Ensure 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

  cause GPU drivers crashing, browser tab being backgrounded for too long, or excessive memory/resource usage leading to the browser discarding the WebGL context.
  fix Implement `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<...>'

  cause 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.
  fix Ensure 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.

Warnings

• breaking This `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.
  Fix: Migrate 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`.
• 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.
  Fix: Always 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.
• 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.
  Fix: Call 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.
• gotcha Loaders (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.
  Fix: Ensure 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.

Install

• npm install super-three npm
• yarn add super-three yarn
• pnpm add super-three pnpm

Imports

• THREE (namespace)
  wrong:

  const THREE = require('super-three');

  correct:

  import * as THREE from '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)
  wrong:

  import { WebGLRenderer } from 'super-three/build/super-three.module.js';

  correct:

  import { Scene, PerspectiveCamera, WebGLRenderer, BoxGeometry, MeshNormalMaterial, Mesh } from 'super-three';

  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)
  wrong:

  import { GLTFLoader } from 'super-three/src/loaders/GLTFLoader.js';

  correct:

  import { GLTFLoader } from 'super-three/examples/jsm/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.

Quickstart

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 );
}