JavaScript Builds

JavaScript / TypeScript applications use a tool or library to transpile WESL for use in WebGPU. To support the wide variety of JavaScript build environments, there are many WESL integration options.

WESL with JavaScript Bundlers

Most front end projects use a JavaScript bundler. WESL plugins are available for many bundlers, including vite, webpack, rollup, esbuild, and rspack.

Install

npm add --save-dev wesl-plugin

Configure your bundler

The WESL plugin supports both ?link (runtime linking) and ?static (build-time linking) import suffixes out of the box.

• ?link — assembles shader files and libraries for runtime linking. Returns a LinkParams object ready to pass to link().

• ?static — links shader files at build time. Returns a WGSL string ready for createShaderModule.

Configuration varies by bundler of course. Here's a vite example:

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

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

The plugin optionally accepts { weslToml: "./path/to/wesl.toml" } to specify an alternate configuration file.

Controlling Dynamic Linking

The link() API enables runtime control of WESL shader transpilation. See Runtime Linking Options.

Controlling Static Bundler Builds

To link statically at build time when using a JavaScript bundler, import with the ?static suffix in JavaScript or TypeScript:

import wgsl from "./shaders/app.wesl?static";

To set conditions during static linking, pass them as query parameters:

import wgsl from "./shaders/app.wesl?MOBILE=true&FUN&static";

Adjusting existing vite configurations

If you started developing a project before switching to WESL, chances are that you imported your WGSL files as static assets, using the assetsInclude option:

/// vite.config.ts
assetsInclude: ['**/*.wgsl'],

/// Importing a file
import shader_url from './example.wgsl'

However, if this option is configured, bundler plugins (?static as well as ?link) will not work. The option must be removed first. Importing a file also works differently, as described above. E.g. for the ?static option, the shader source will be returned instead of a static URL.

No Bundler Dynamic Linking

See the unbundled example which uses the wesl library API directly.

No Bundler Static Linking

Use the wesl-link command line tool to link WGSL/WESL shaders together. The linked WGSL is written to stdout.

• --src WGSL/WESL shader files to bundle into the package, using glob syntax. (default: ./shaders/*.w[eg]sl)

• --rootModule start linking from this module. The linked result includes all WGSL/WESL elements indirectly referenced from the root module. (default: main)

• --conditions enable these space-separated conditional compilation flags. (default: <none>)

• --baseDir root directory containing WGSL/WESL files. The source files are mapped to imports starting at the base directory. (default: ./shaders)

• --projectDir directory containing package.json (default: current directory).

Using WESL Without a Package Manager

CDN

• jsdelivr https://cdn.jsdelivr.net/npm/wesl/+esm
• unpkg https://unpkg.com/wesl
• esm.sh https://esm.sh/wesl

Deno

deno install npm:wesl