naga-wasi-cli

High-performance WASI-compiled naga shader compiler for Node.js.

Why WASI?

Unlike pure WebAssembly which requires JavaScript bridging for all I/O operations, WASI provides:

• Direct filesystem access via preopened directories - no JS bridging overhead
• Native stdio handling - stdin/stdout/stderr work seamlessly
• Near-native I/O performance - file operations happen at the WASI runtime level
• Lower memory overhead compared to emscripten-style filesystem emulation

This makes naga-wasi-cli significantly faster for batch shader compilation compared to pure WASM solutions.

Installation

npm install naga-wasi-cli
# or
npx naga-wasi-cli

Requires Node.js 20.0.0 or later (for stable WASI support).

Usage

# Validate a WGSL shader
npx naga-wasi-cli shader.wgsl

# Convert WGSL to GLSL (vertex shader)
npx naga-wasi-cli shader.wgsl output.vert

# Convert WGSL to GLSL with profile
npx naga-wasi-cli --profile core450 shader.wgsl output.vert

# Convert WGSL to SPIR-V
npx naga-wasi-cli shader.wgsl output.spv

# Convert WGSL to Metal
npx naga-wasi-cli shader.wgsl output.metal

# Convert WGSL to HLSL
npx naga-wasi-cli shader.wgsl output.hlsl

# Convert GLSL to WGSL (shader stage from filename: shader.frag.glsl)
npx naga-wasi-cli shader.frag.glsl output.wgsl

# Bulk validation
npx naga-wasi-cli --bulk-validate *.wgsl

# Generate DOT graph
npx naga-wasi-cli shader.wgsl output.dot

Options

CLI interface is fully compatible with upstream naga-cli.

Usage: naga [OPTIONS] [<files...>]

Positional Arguments:
  files                 the input and output files

Options:
  --validate            bitmask of ValidationFlags (use 0 to disable)
  --index-bounds-check-policy
                        Restrict | ReadZeroSkipWrite | Unchecked
  --buffer-bounds-check-policy
  --image-load-bounds-check-policy
  --entry-point         the shader entrypoint
  --profile             GLSL profile (es, core, es330, core450, etc.)
  --shader-model        HLSL shader model (50, 51, 60, etc.)
  --spirv-version       SPIR-V version (1.0, 1.4, etc.)
  --shader-stage        vert | frag | compute
  --input-kind          wgsl | glsl | spv | bin
  --metal-version       Metal version (1.0, 2.4, etc.)
  --keep-coordinate-space
  --dot-cfg-only
  --stdin-file-path     file path when reading from stdin
  -g                    generate debug symbols (spv-out only)
  --compact             compact IR and revalidate
  --before-compaction   write IR before compaction
  --bulk-validate       validate multiple files
  --version
  --override            override values (foo=N,bar=M)
  -D                    defines for GLSL parser
  --capabilities        parsing/validation capabilities

Supported Formats

| Input | Output | |--------|--------| | WGSL | WGSL | | GLSL | GLSL (.vert, .frag, .comp) | | SPIR-V | SPIR-V | | Bincode | Bincode | | | MSL | | | HLSL | | | DOT |

Building from Source

# Install Rust and add WASI target
rustup target add wasm32-wasip1

# Build
npm run build

License

MIT OR Apache-2.0

Based on naga from the wgpu project.