wgslVitePlugin and transformWgsl

Vite/Rollup transform that turns .wgsl files into JavaScript modules exporting ShaderSource v1 objects. Use the plugin in Vite apps and transformWgsl() in tests or custom tooling.

Import

import wgslVitePlugin, { transformWgsl } from "@vgpu/wgsl/loader-vite";
import type { ViteLoadResult } from "@vgpu/wgsl/loader-vite";

Signature

interface ViteLoadResult { readonly code: string; readonly map: null }
 
interface WgslVitePluginOptions {
  readonly minify?: boolean | { readonly whitespace?: boolean; readonly identifiers?: "none" | "safe" };
}
 
interface TransformWgslOptions extends WgslVitePluginOptions {
  readonly source: string;
  readonly id: string;
  readonly onDependency?: (absPath: string) => void;
}
 
declare function transformWgsl(source: string, id: string, options?: WgslVitePluginOptions): Promise<ViteLoadResult>;
declare function transformWgsl(opts: TransformWgslOptions): Promise<ViteLoadResult>;
declare function wgslVitePlugin(options?: WgslVitePluginOptions): {
  readonly name: string;
  readonly transform: (this: { addWatchFile(fileName: string): void }, source: string, id: string) => Promise<ViteLoadResult | null>;
};

Parameters

Returns: Promise<ViteLoadResult> from transformWgsl() with JavaScript module code and map: null; plugin transform returns that result for .wgsl ids or null for other ids.

Throws: Any resolveShader() VGPU-WGSL-* or VGPU-RESOLVE-MODULE-BINDING error when import graph resolution fails — fix imports, module purity, package resolution, duplicates, or WGSL validation/minification. Throws: VGPU-WGSL-MINIFY-IDENTIFIERS or VGPU-WGSL-MINIFY-BLOCK when minification options/source are invalid for a leaf file — pass a valid minify mode or fix unterminated comments.

Examples

import wgslVitePlugin from "@vgpu/wgsl/loader-vite";
 
const viteConfig = {
  plugins: [wgslVitePlugin({ minify: true })],
};
 
export default viteConfig;

import { transformWgsl } from "@vgpu/wgsl/loader-vite";
 
const result = await transformWgsl(
  "@compute @workgroup_size(1) fn main() {}",
  "/shader.wgsl",
  { minify: { whitespace: true } },
);
 
console.log(result.map === null, result.code.includes("version"));

Notes

• Transform output default-exports ShaderSource v1: { version: 1, wgsl: "..." }.
• wgslVitePlugin() only handles ids ending with .wgsl; use transformWgsl() directly for tests and non-Vite tooling.
• Leaf shader transforms do not call onDependency because Vite already tracks the entry file. Imported graph transforms call it for transitive deps.
• A leaf WGSL file may declare entry resources. Shared/imported modules must be pure: no @group/@binding outside the entry.
• The transform calls resolveShader({ validate: false }) for imported graphs; parsing, purity checks, DCE, mangling, and optional minification still apply.
• See also: ShaderSource, resolveShader, wgslWebpackLoader, and the nextjs guide (npx vgpu docs cat nextjs.md) for the ambient .d.ts that types .wgsl imports.