Getting Started JavaScript

Quick Start

Here's a 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";

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

Link at Runtime

/// <reference types="wesl-plugin/suffixes" />
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
edition = "2026_pre"
include = [ "./shaders/**/*.w[eg]sl" ]
root = "./shaders"
dependencies = ["random_wgsl"]

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

• edition - mark WESL edition for compatibility.

  edition = "2026_pre"

• include - an array of globs locating shader files.

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

• root - 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 root.

  default root = "./shaders"

• dependencies - list of npm package names for shader dependencies, or "auto" for auto-detection.

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

  default - dependencies = "auto"

• exclude - glob patterns to exclude directories (optional).

• package-manager - specify "npm" or "cargo" (optional, auto-detected).

wesl.toml is used by development tools like the wesl-plugin 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.