miniray

WGSL minifier for WebGPU shaders - WebAssembly build.

This package provides a WASM build of the miniray that runs in browsers and Node.js.

Installation

npm install miniray

Browser Usage

<script src="node_modules/miniray/wasm_exec.js"></script>
<script src="node_modules/miniray/lib/browser.js"></script>
<script>
  (async () => {
    await miniray.initialize({ wasmURL: 'node_modules/miniray/miniray.wasm' });

    const result = miniray.minify(`
      @vertex fn main() -> @builtin(position) vec4f {
        return vec4f(0.0);
      }
    `);

    console.log(result.code);
    // "@vertex fn main()->@builtin(position) vec4f{return vec4f(0.0);}"
  })();
</script>

ESM Usage

import { initialize, minify } from 'miniray';

await initialize({ wasmURL: '/path/to/miniray.wasm' });

const result = minify(source, {
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true,
});

Node.js Usage

const { initialize, minify } = require('miniray');

await initialize(); // Automatically finds miniray.wasm

const result = minify(source);
console.log(result.code);

API

initialize(options)

Initialize the WASM module. Must be called before minify(), reflect(), or validate().

interface InitializeOptions {
  wasmURL?: string | URL;           // Path or URL to miniray.wasm
  wasmModule?: WebAssembly.Module;  // Pre-compiled module
}

minify(source, options?)

Minify WGSL source code.

interface MinifyOptions {
  minifyWhitespace?: boolean;           // Remove whitespace (default: true)
  minifyIdentifiers?: boolean;          // Rename identifiers (default: true)
  minifySyntax?: boolean;               // Optimize syntax (default: true)
  mangleExternalBindings?: boolean;     // Mangle uniform/storage names (default: false)
  treeShaking?: boolean;                // Remove unused declarations (default: true)
  preserveUniformStructTypes?: boolean; // Keep struct types used in uniforms (default: false)
  keepNames?: string[];                 // Names to preserve from renaming
  sourceMap?: boolean;                  // Generate source map (default: false)
  sourceMapSources?: boolean;           // Include source in sourcesContent (default: false)
}

interface MinifyResult {
  code: string;           // Minified code
  errors: MinifyError[];  // Parse/minification errors
  originalSize: number;   // Input size in bytes
  minifiedSize: number;   // Output size in bytes
  sourceMap?: string;     // Source map JSON (if sourceMap: true)
}

reflect(source)

Extract binding information, struct layouts, and entry points from WGSL source.

interface ReflectResult {
  bindings: BindingInfo[];
  structs: Record<string, StructLayout>;
  entryPoints: EntryPointInfo[];
  errors: string[];
}

interface BindingInfo {
  group: number;
  binding: number;
  name: string;
  addressSpace: string;    // "uniform", "storage", "handle"
  accessMode?: string;     // "read", "write", "read_write" (for storage)
  type: string;
  layout: StructLayout | null;  // null for textures/samplers
}

interface StructLayout {
  size: number;
  alignment: number;
  fields: FieldInfo[];
}

interface FieldInfo {
  name: string;
  type: string;
  offset: number;
  size: number;
  alignment: number;
  layout?: StructLayout;   // for nested structs
}

interface EntryPointInfo {
  name: string;
  stage: string;           // "vertex", "fragment", "compute"
  workgroupSize: number[] | null;  // [x, y, z] for compute, null otherwise
}

Example:

const result = reflect(`
  struct Uniforms { time: f32, resolution: vec2<u32> }
  @group(0) @binding(0) var<uniform> u: Uniforms;
  @compute @workgroup_size(8, 8) fn main() {}
`);

console.log(result.bindings[0]);
// {
//   group: 0, binding: 0, name: "u",
//   addressSpace: "uniform", type: "Uniforms",
//   layout: {
//     size: 16, alignment: 8,
//     fields: [
//       { name: "time", type: "f32", offset: 0, size: 4, alignment: 4 },
//       { name: "resolution", type: "vec2<u32>", offset: 8, size: 8, alignment: 8 }
//     ]
//   }
// }

console.log(result.entryPoints[0]);
// { name: "main", stage: "compute", workgroupSize: [8, 8, 1] }

Memory layouts follow the WGSL specification:

• vec3 has alignment=16 but size=12
• Struct members are aligned to their natural alignment
• Struct size is rounded up to struct alignment

validate(source, options?)

Validate WGSL source for semantic errors, type mismatches, and uniformity violations.

interface ValidateOptions {
  strictMode?: boolean;                                    // Treat warnings as errors
  diagnosticFilters?: Record<string, 'error' | 'warning' | 'info' | 'off'>;
}

interface ValidateResult {
  valid: boolean;              // true if no errors
  diagnostics: DiagnosticInfo[];
  errorCount: number;
  warningCount: number;
}

interface DiagnosticInfo {
  severity: 'error' | 'warning' | 'info' | 'note';
  code?: string;               // e.g., "E0200"
  message: string;
  line: number;                // 1-based
  column: number;              // 1-based
  endLine?: number;
  endColumn?: number;
  specRef?: string;            // WGSL spec reference
}

Example:

const result = validate(`
  fn foo() -> f32 {
    var x: i32 = 1;
    return x;  // Error: returning i32 from f32 function
  }
`);

console.log(result.valid);  // false
console.log(result.errorCount);  // 1
console.log(result.diagnostics[0]);
// {
//   severity: "error",
//   code: "E0200",
//   message: "cannot return 'i32' from function returning 'f32'",
//   line: 4,
//   column: 5
// }

With options:

const result = validate(source, {
  strictMode: true,  // Treat warnings as errors
  diagnosticFilters: {
    derivative_uniformity: 'off',  // Disable uniformity warnings
  },
});

Validation checks:

• Type mismatches (assignments, returns, function calls)
• Undefined symbols (variables, functions, types)
• Invalid operations (operators, indexing, member access)
• Entry point requirements
• Uniformity analysis (textureSample, derivatives)
• WGSL spec compliance

isInitialized()

Returns true if the WASM module is initialized.

version

The version of the minifier.

Options

minifyWhitespace

Remove unnecessary whitespace and newlines.

minifyIdentifiers

Rename local variables, function parameters, and helper functions to shorter names. Entry points and API-facing declarations are preserved.

minifySyntax

Apply syntax-level optimizations like numeric literal shortening.

mangleExternalBindings

Control how var<uniform> and var<storage> names are handled:

• false (default): Original names are preserved in declarations, short aliases are used internally. This maintains compatibility with WebGPU's binding reflection APIs.
• true: Names are mangled directly for smaller output, but breaks binding reflection.

// Input
const shader = `
@group(0) @binding(0) var<uniform> uniforms: f32;
fn getValue() -> f32 { return uniforms * 2.0; }
`;

// With mangleExternalBindings: false (default)
// Output: "@group(0) @binding(0) var<uniform> uniforms:f32;let a=uniforms;fn b()->f32{return a*2.0;}"

// With mangleExternalBindings: true
// Output: "@group(0) @binding(0) var<uniform> a:f32;fn b()->f32{return a*2.0;}"

treeShaking

Enable dead code elimination to remove unused declarations (default: true):

minify(source, {
  treeShaking: true,  // Remove unreachable code
});

preserveUniformStructTypes

Automatically preserve struct type names that are used in var<uniform> or var<storage> declarations (default: false):

// Input
const shader = `
struct MyUniforms { time: f32 }
@group(0) @binding(0) var<uniform> u: MyUniforms;
@fragment fn main() -> @location(0) vec4f { return vec4f(u.time); }
`;

// With preserveUniformStructTypes: false (default)
// struct MyUniforms -> struct a

// With preserveUniformStructTypes: true
// struct MyUniforms preserved
minify(source, {
  preserveUniformStructTypes: true,
});

This is particularly useful for frameworks like PNGine that detect builtin uniforms by struct type name.

keepNames

Array of identifier names that should not be renamed:

minify(source, {
  minifyIdentifiers: true,
  keepNames: ['myHelper', 'computeValue'],
});

sourceMap

Generate a source map to debug minified shaders by mapping back to original source:

const result = minify(source, {
  minifyIdentifiers: true,
  sourceMap: true,
});

console.log(result.code);
// "const a=42;fn b()->i32{return a;}"

console.log(result.sourceMap);
// '{"version":3,"sources":[],"names":["longVariable","myFunction"],"mappings":"MAAAA,..."}'

The source map follows the Source Map v3 specification and includes:

• version: Always 3
• names: Original names of renamed identifiers
• mappings: VLQ-encoded position mappings

sourceMapSources

Include the original source code in the source map's sourcesContent field for self-contained debugging:

const result = minify(source, {
  sourceMap: true,
  sourceMapSources: true,  // Embed original source
});

const map = JSON.parse(result.sourceMap);
console.log(map.sourcesContent);
// ["const longVariable = 42;\nfn myFunction() -> i32 { return longVariable; }"]

Source Map Example: Complete Workflow

import { initialize, minify } from 'miniray';

await initialize({ wasmURL: '/miniray.wasm' });

const source = `
const longVariableName = 42;

fn helperFunction(value: i32) -> i32 {
    return value * 2;
}

@compute @workgroup_size(1)
fn main() {
    let result = helperFunction(longVariableName);
}
`;

const result = minify(source, {
  minifyWhitespace: true,
  minifyIdentifiers: true,
  sourceMap: true,
  sourceMapSources: true,
});

console.log('Minified code:');
console.log(result.code);
// "const a=42;fn b(c:i32)->i32{return c*2;}@compute @workgroup_size(1) fn main(){let d=b(a);}"

console.log('\nSource map:');
const map = JSON.parse(result.sourceMap);
console.log('Names:', map.names);
// Names: ["longVariableName", "helperFunction", "value", "result"]

// To use the source map inline:
const codeWithSourceMap = result.code +
  '\n//# sourceMappingURL=data:application/json;base64,' +
  btoa(result.sourceMap);

Using with Bundlers

Vite

import { initialize, minify } from 'miniray';
import wasmURL from 'miniray/miniray.wasm?url';

await initialize({ wasmURL });

Webpack

import { initialize, minify } from 'miniray';

// Configure webpack to handle .wasm files
await initialize({ wasmURL: new URL('miniray/miniray.wasm', import.meta.url) });

Pre-compiling WASM

For better performance when creating multiple instances:

const wasmModule = await WebAssembly.compileStreaming(
  fetch('/miniray.wasm')
);

// Share module across workers
await initialize({ wasmModule });

Performance

• WASM binary: ~3.6MB
• Initialization: ~100ms (first load)
• Transform: <1ms for typical shaders

License

MIT