Start here

Installation

NatureGL Sky ships as a folder. It has a runnable demo, the library source, and a prebuilt ES module with TypeScript declarations. Pick whichever of the three integration paths suits your build.

#Requirements

three.js	`>= 0.180` as a peer dependency. Developed and tested on r186
Renderer	`THREE.WebGLRenderer` with WebGL2. The library does not need WebGPU
Node	18 or newer, only for the demo and the build scripts
Camera	`THREE.PerspectiveCamera`. Clouds are reconstructed for one main camera

#Run the demo first

#Unpack and install

bash

cd naturegl-sky
npm install

#Start the dev server

bash

npm run dev

It opens http://localhost:5181/demo/: an island, open sea and a fly camera under the live sky. The demo page lists every control.

#Build or test (optional)

bash

npm run build   # library -> build/, static demo -> dist/
npm test        # headless GPU smoke test of every preset -> test-results/*.png + fps

#What's in the folder

naturegl-sky/

├── src/the library: no DOM UI, no scenery│   ├── SkySystem.jsthe facade: create, update, presets, quality, outputs│   ├── post/SkyPostPass (optional)│   ├── render/cloud march + TAA, bakes, backdrop│   ├── shaders/GLSL as template strings│   ├── materials/cloud-shadow material patch + GLSL snippet│   ├── core/astronomy, CPU atmosphere twin│   └── config/QualityLevels.js, defaults.js, presets/├── build/prebuilt ESM bundle + .d.ts├── demo/the full demo app├── examples/basic/minimal Vite integration├── examples/cdn/plain JS + import map└── scripts/smoke.mjs and dev helpers

#Add it to your project

Copy build/ into your project, for example as lib/naturegl-sky/, and import from it. three stays an external import, so your bundler or an import map resolves it.

import { SkySystem } from './lib/naturegl-sky/index.js';

The bundle has a source map and .d.ts files next to it, so editors get types and go-to-definition.

src/ is plain ES modules with JSDoc. GLSL lives in .glsl.js template strings, so it runs with or without a bundler.

import { SkySystem } from './vendor/naturegl-sky/src/index.js';

Choose this if you want to read or patch the shaders in place.

Point an alias at the source. The demo itself uses this path.

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    alias: { 'naturegl-sky': '/path/to/naturegl-sky/src/index.js' },
  },
});

import { SkySystem } from 'naturegl-sky';

#Without a bundler

An import map resolves three from a CDN. The library comes from your copy of build/.

index.html

<script type="importmap">
  { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.186.0/build/three.module.js" } }
</script>
<script type="module">
  import * as THREE from 'three';
  import { SkySystem } from './lib/naturegl-sky/index.js';
</script>

examples/cdn/index.html is a complete page. Serve the package root with any static server, such as npx http-server ., and open /examples/cdn/.

#Next

Quick startA sky, sun and cloud shadows in about 30 lines.The demoEvery key and panel in the full demo.API referenceEvery option, method, output and event.