README.md

Simple Three.js + TypeScript + Vite Starter

This scaffolding lets you easily get started with using Three.js and TypeScript.

Features

• Vite development environment
• Full TypeScript support
• Asset management
• Debugging GUI and Stats
• Social media and description overlay
• Simple loading animation
• Including shader chunks
• LYGIA Shader Library

Prerequisites

• Node.js
• yarn OR npm

💡 This project uses yarn@3.2.1 and npm@8.1.2. Other versions might lead to different package resolutions, proceed with caution. Example commands use yarn.

Installation

To use this scaffolding, run the following command:

git clone https://github.com/mayacoda/simple-threejs-typescript-starter my-threejs-project
cd my-threejs-project
yarn install

✅ If you are on GitHub, create a new repository using this repository as a template by clicking the green Use this template button in the top right.

Development

The starter includes a pre-configured Vite server which you can use to run and develop your project. To start the development server, run the following command:

yarn dev

To build the project, run:

yarn build

And if you wish to automatically start a server to preview your build, you can run:

yarn build && yarn preview

Engine

The starter includes a utility Engine class which is responsible for setting up the renderer, render loop, scene, camera, and controls. All you have to do is provide a class that follows the Experience interface and pass it to the Engine constructor.

// in src/main.ts

import { Engine } from './engine/Engine'
import { Demo } from './demo/Demo'

new Engine({
  canvas: document.querySelector('#canvas') as HTMLCanvasElement,
  experience: Demo,
  info: {
    twitter: 'https://twitter.com/maya_ndljk',
    github: 'https://github.com/mayacoda/simple-threejs-typescript-starter',
    description: 'A simple Three.js + Typescript + Vite starter project',
    documentTitle: 'Three.js + Typescript + Vite',
    title: 'A cube on a plane',
  },
})

Then inside the class which implements Experience, you have access to the entire engine and its components.

// in src/demo/Demo.ts

import { Engine } from '../engine/Engine'
import { Experience } from '../engine/Experience'
import { Resource } from '../engine/Resources'

export class Demo implements Experience {
  // list of resources required by the experience
  resources: Resource[] = []

  constructor(private engine: Engine) {}

  // initialize scene -- called by tne Engine after resources are loaded
  init() {}

  // called on resize
  resize() {}

  // called on each render
  update() {}
}

Removing the example scene

To demonstrate how to use the scaffolding, this project includes an example scene. To remove it and start with a blank project, run:

yarn cleanup

This will also clear the content of this README.md file to just the basic commands for running the project.

Serving Resources

Resources loaded through THREE.js loaders need to go in the /public directory to avoid being compiled by Vite. This includes textures and models.

More information about Vite's asset handling can be found here.

Including Shader Chunks

Shaders are loaded using the vite-plugin-glsl Vite plugin and can be located anywhere within the /src directory.

The starter also includes the LYGIA Shader Library. To use it, import the shader chunks you need in your shader file.

// in src/demo/shader.frag

#include "../shaders/lygia/color/palette/water.glsl"

varying vec2 vUv;

void main() {
    gl_FragColor = vec4(water(vUv.y), 1.0);
}