wgsl-wasm-transpiler-bundler

0.0.1 verified Fri May 01 auth: no javascript

A Rust-based WGSL shader compiler and cross-transpiler that converts WGSL to GLSL, HLSL, Metal, or SPIR-V. v0.0.1 is an early release with no regular release cadence yet. Differentiators: runs in Node.js and browser via WASM, single-function API, supports SPIR-V binary and assembly output. Requires manual WASM initialization via `init()` before any compilation calls. Competing with naga and glslang, but lighter and purely WGSL→others.

Common errors

error TypeError: compileShader is not a function ↓

cause Importing default instead of named export.

fix

Use import { compileShader } from 'wgsl-wasm-transpiler-bundler'

error RuntimeError: unreachable (or WebAssembly.instantiate(): expected magic word) ↓

cause WASM binary not loaded or init() not called properly.

fix

Ensure you are using the correct path to the WASM file and call init() with await.

error Error: Unknown format: 'spirv_binary' ↓

cause Using wrong format string; must be exactly one of the supported formats.

fix

Use 'spirv' for binary or 'spirv-asm' for text. Run getSupportedFormats() to see all.

Warnings

breaking Calling compileShader before init() throws: 'WASM not initialized' or panics. ↓

fix Always call init() (and await in browser) before any other API function.

gotcha init() is synchronous in Node.js but asynchronous in browser. If you await in Node, it's fine, but forgetting await in browser will cause a runtime error. ↓

fix Use await init() in both environments; it works in Node too.

gotcha compileShader throws on invalid WGSL or unsupported format. Unclear error messages may mention Rust panics. ↓

fix Validate WGSL before passing. Use getSupportedFormats() to check format. Wrap in try/catch.

Install

npm install wgsl-wasm-transpiler-bundler

yarn add wgsl-wasm-transpiler-bundler

pnpm add wgsl-wasm-transpiler-bundler

Imports

compileShader

wrong

import compileShader from 'wgsl-wasm-transpiler-bundler'

correct

import { compileShader } from 'wgsl-wasm-transpiler-bundler'

ESM; named export only. No default export.

init
wrong
```
const init = require('wgsl-wasm-transpiler-bundler')
```
correct
```
import { init } from 'wgsl-wasm-transpiler-bundler'
```
Required before compileShader. Returns a promise in browser (await), sync in Node (call once).
getSupportedFormats
```
import { getSupportedFormats } from 'wgsl-wasm-transpiler-bundler'
```
Returns string array like ['wgsl','glsl','hlsl','metal','spirv','spirv-asm'].

Quickstart

Initialize WASM and compile a trivial WGSL fragment shader to GLSL.

import { init, compileShader } from 'wgsl-wasm-transpiler-bundler';

const wgsl = `@fragment fn main() -> @location(0) vec4<f32> {
  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
}`;

// Browser: await init(); Node: init(); then use
await init();
const glsl = compileShader(wgsl, 'glsl');
console.log(glsl);