stellar-gl

A lightweight and modular WebGL layer built on top of Three.js — designed to integrate seamlessly with stellar-kit and stellar-libs. stellar-gl supports both single-canvas setups for full-page experiences and per-section canvases integrated into modular websites.

✨ Features

• Canvas setup with custom renderer, camera, and tick support
• Perspective camera with getViewSize helpers
• App class to manage lifecycle (tick, resize, destroy)
• Optional WorldManager for DOM-based modular WebGL components
• Support for DOM-to-Three position/size mapping (Tracker, boundsToView)
• Three.js renderer with antialiasing, alpha, and powerPreference: "high-performance"

📦 Installation

npm install @linear_non/stellar-gl

Requires Three.js and stellar-kit. You can install all together:

npm install three @linear_non/stellar-kit

📁 Folder Structure

stellar-gl/
├── classes/
│   ├── App.js            # Main lifecycle controller
│   ├── Canvas.js         # Renderer, camera, scene
│   ├── Renderer.js       # Custom Three.js renderer
│   ├── Camera.js         # Perspective camera with utils
│   ├── WorldManager.js   # Optional per-component system
├── utils/
│   ├── boundsToView.js   # Convert DOM bounds to 3D space
│   ├── Tracker.js        # Tracks DOM elements in 3D space
├── libraries/
│   └── three/            # Only used to load the THREE library
├── dev/                  # Vite playground (test cube, scenes)
├── index.js              # Entry point for npm package
└── vite.config.js        # Dev config

🧪 Local Development

npm install
npm run dev

This runs a Vite playground. You can build scenes like a cube test or DOM-synced planes using the App class and either a WorldClass or a WorldManager.

🛠️ Usage Example

import { App } from "@linear_non/stellar-gl"
import { setupKit } from "@linear_non/stellar-kit"
import { Smooth } from "@linear_non/stellar-libs"

setupKit()

const app = new App({
  canvas: document.querySelector("canvas"),
  WorldClass: HeroGL,
})

For multiple GL components tied to DOM, use the WorldManager instead and pass components: [...] instead of WorldClass.

✅ TODO

• [ ] Add ShaderPlane base class
• [ ] Add ModelLoader utility for DRACO/gltf
• [ ] Add TextureLoader utility
• [ ] Add support for RenderTargets
• [ ] Add FrustumCulling utils

Made with ❤️ by Non-Linear Studio