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