Setup

These tutorials use the current luma.gl v9.3 API. The runnable sources in examples/tutorials remain the canonical reference for the code shown on these pages.

This tutorial will walk you through setting up a basic development project for luma.gl applications using Vite tooling. Later tutorials will build on this one, so we recommend going through it first.

Note: It is assumed for these tutorials that you have some basic knowledge of GPU APIs and JavaScript programming.

A Minimal Application

Create a new folder on your file system to store your new project. Then let's create a file app.ts in the project root folder and add the following to it:

import type {AnimationProps} from '@luma.gl/engine';
import {AnimationLoopTemplate} from '@luma.gl/engine';

export default class AppAnimationLoopTemplate extends AnimationLoopTemplate {
  override onRender({device}: AnimationProps) {
    const renderPass = device.beginRenderPass({
      clearColor: [0, 0, 0, 1],
      clearDepth: 1
    });
    renderPass.end();
  }
}

This will be the basic structure of most luma.gl applications. AnimationLoopTemplate provides the lifecycle hooks, while the page entry point chooses the rendering backend and starts the loop.

Now create an index.html file to bootstrap the application:

<!doctype html>
<script type="module">
  import {makeAnimationLoop} from '@luma.gl/engine';
  import {webgpuAdapter} from '@luma.gl/webgpu';
  import {webgl2Adapter} from '@luma.gl/webgl';
  import AppAnimationLoopTemplate from './app.ts';

  makeAnimationLoop(AppAnimationLoopTemplate, {
    adapters: [webgpuAdapter, webgl2Adapter]
  }).start();
</script>
<body style="margin: 0;"></body>

When the page loads, luma.gl will try webgpuAdapter first and fall back to webgl2Adapter when WebGPU is unavailable.

Build Tooling

We will need the following files in the project folder:

- package.json
- vite.config.ts
- app.ts
- index.html

From the command line, first run

mkdir luma-demo
cd luma-demo
npm init -y

to set up our project directory and initialize npm.

Next run

npm i @luma.gl/engine @luma.gl/webgl @luma.gl/webgpu
npm i -D vite typescript

to install our dependencies.

Open the file package.json (created when we initialized npm), and add the following to the scripts block:

{
  "scripts": {
    "start": "vite",
    "build": "tsc && vite build",
    "serve": "vite preview"
  },
  "dependencies": {
    "@luma.gl/engine": "9.3.0-alpha.4",
    "@luma.gl/webgl": "9.3.0-alpha.4",
    "@luma.gl/webgpu": "9.3.0-alpha.4"
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "vite": "^7.2.2"
  }
}

The full contents of the package.json should be the following (dependency version numbers might differ):

{
  "name": "luma-demo",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "vite",
    "build": "tsc && vite build",
    "serve": "vite preview"
  },
  "dependencies": {
    "@luma.gl/engine": "9.3.0-alpha.4",
    "@luma.gl/webgl": "9.3.0-alpha.4",
    "@luma.gl/webgpu": "9.3.0-alpha.4"
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "vite": "^7.2.2"
  }
}

Create a file vite.config.ts in the project root and add the following to it:

import {defineConfig} from 'vite';

export default defineConfig({
  server: {open: true}
});

and run

npm start

from the command line. If all went well, a tab should open in your default browser, and you should see a black canvas fill the page.

A Minimal Application​

Build Tooling​

A Minimal Application

Build Tooling