Getting Started JavaScript

Quick Start

Here's typical setup for a front end application using wesl and wesl-plugin/vite .

Install

npm install wesl                      # for runtime linking
npm install --save-dev wesl-plugin    # for bundler integration

Configure Vite

/// vite.config.ts
import viteWesl from "wesl-plugin/vite";
import { linkBuildExtension } from "wesl-plugin";

export default {
  plugins: [viteWesl({ extensions: [linkBuildExtension] })],
};

Link at Runtime

import { link, createWeslDevice } from "wesl";
import appWesl from "../shaders/app.wesl?link";

async function example() {
  const device = createWeslDevice(await navigator.gpu.requestAdapter()); 
  const linked = await link(appWesl);
  const shaderModule = linked.createShaderModule(device, {});
}

Other Build Environments

WESL is easy to integrate into a diverse variety of JavaScript/TypeScript build environments. See JavaScript Builds.

Default Project Organization

./wesl.toml - optional project configuration file

./shaders - default location for .wesl and .wgsl files.

wesl.toml

Customize configuration for your project by creating a wesl.toml file in the same directory as package.json. Here's an example:

/// wesl.toml
weslFiles = [ "./shaders/**/*.w[eg]sl" ]
weslRoot = "./shaders" 
dependencies = ["random_wgsl"]

wesl.toml settings below. All settings are optional. A wesl.toml is not required if the default setting are sufficient.

• weslFiles - an array of globs locating shader files.

  default weslFiles = [ "./shaders/**/*.w[eg]sl" ]

• weslRoot - ignored prefix for shader module paths.

  import statements inside wesl files use module paths (with :: separators). The module paths are mapped directly from shader file paths skipping past the weslRoot.

  default weslRoot = [ "./shaders" ]

• dependencies - list of npm package names for shader dependencies

  All dependencies should also be listed in package.json. Only direct dependencies should be listed.

  default - dependencies = []

wesl.toml is used by development tools like the wesl-plugin, wesl-packager, and the forthcoming WESL language server.

Next Steps

See Runtime Linking for more options to control linking at runtime.

See JavaScript Builds for more ways to integrate WESL into your JavaScript or TypeScript project.

See WESL Features for shader language enhancements in WESL.

See WESL-js Examples for example projects.