Skip to main content

Setup

caution

The tutorial pages have not yet been updated for luma.gl v9.

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 {AnimationLoop} from '@luma.gl/engine';

const loop = new AnimationLoop({
  override onInitialize({device}: AnimationProps) {
    // Setup logic goes here
  },

  override onFinalize({device}: AnimationProps) {
    // Teardown logic goes here
  },

  override onRender({device}: AnimationProps) {
    // Drawing logic goes here
  }
});

loop.start();

This will be the basic structure of most luma.gl applications. To make sure everything works, let's add a draw command:

import {AnimationLoop} from '@luma.gl/engine';
import {clear} from '@luma.gl/webgl';

const loop = new AnimationLoop({
  override onRender({device}) {
    // Drawing logic goes here
    clear(device, {color: [0, 0, 0, 1]});
  }
});

loop.start();

Since this is a web application, you will also want to create a minimal index.html web page to start the app:

<!doctype html>
<script type="module">
  import './app.ts';
</script>
<body style="margin: 0;">
  <canvas id="canvas" style="width: 100vw; height: 100vh;"></canvas>
</body>

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
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",
    "serve": "vite preview"
  },
  "dependencies": {
    "@luma.gl/engine": "9.1.0-alpha.17",
    "@luma.gl/webgl": "9.1.0-alpha.17",
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "vite": "^5.0.0"
  }
}

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

{
  "name": "luma-demo",
  "version": "1.0.0",
  "description": "",
  "keywords": [],
  "author": "",
  "license": "ISC",
  "main": "index.js",
  "scripts": {
    "start": "vite",
    "serve": "vite preview"
  },
  "dependencies": {
    "@luma.gl/engine": "9.1.0-alpha.17",
    "@luma.gl/webgl": "9.1.0-alpha.17",
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "vite": "^5.0.0"
  }
}

Create a file vite.config.js 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 rectangle at the top left of your screen.