JavaScript Builds

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

• WESL plugins are available for most popular JavaScript / TypeScript bundlers. Bundler based projects can choose to link WESL dynamically at runtime, or statically at build time.

• Projects that don't use a bundler can link dynamically using the wesl library directly, or link statically using the wesl-link command line tool.

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 takes two options:

• weslToml - configure an alternate wesl.toml configuration file.

• extensions - configure which plugin features will be available.

  • linkBuildExtension - for linking at runtime.

    import with the ?link suffix in JavaScript/TypeScript programs to conveniently assemble shader files and libraries for linking at runtime. Reads the wesl.toml file to find local shader files and libraries.

    Returns a LinkParams object ready to use for runtime linking.

  • staticBuildExtension - for linking at build time.

    import with the ?static suffix in JavaScript/TypeScript programs to link shader files at build time. Reads the wesl.toml file to find local shader files and libraries,

    Returns a wgsl string ready to use for createShaderModule.

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

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

  export default {
    plugins: [
      viteWesl({ 
        weslToml: "./variations/mobileApp.wesl.toml",
        extensions: [linkBuildExtension] 
      })
    ],
  };

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, configure the staticBuildExtension and then import with the ?static suffix in JavaScript or TypeScript:

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

To set conditions during static linking pass them on the with name=value pairs in the import statement:

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

No Bundler Dynamic Linking

See the unbundled example.

No Bundler Static Linking

See the wesl-link command line tool.