miniray

library0.3.1jsnpmunverified

A WGSL minifier for WebGPU shaders, distributed as a WebAssembly build for browsers and Node.js (v0.3.x, monthly releases). Unlike general JS minifiers, it specializes in WGSL: it understands shader syntax, can tree-shake unused declarations, rename identifiers, optimize syntax, and optionally mangle external bindings. Ships TypeScript definitions and supports source maps via source-map crate. Relies on an async WASM initialization step that is a common footgun.

devops

npm install miniray

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MINIRAY

miniray

devopsjavascriptv0.3.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

initialize

✓ import { initialize } from 'miniray'

✗ const { initialize } = require('miniray') // CJS works but is not recommended for browser

ESM and CJS both supported. In browsers, also need to load wasm_exec.js.

minify

✓ import { minify } from 'miniray'

✗ import miniray from 'miniray' // This is a default import, which does not exist! 'miniray' has no default export.

Only named exports; no default export.

MinirayOptions

✓ import type { MinifyOptions } from 'miniray'

✗ import { MinifyOptions } from 'miniray' // It's a type, not a runtime value; use 'import type' with TypeScript (or isolatedModules).

Types can be imported using type-only imports when using TypeScript.

Demonstrates async initialization, then minifies a WGSL shader with whitespace, identifier, syntax, and tree-shaking enabled.

import { initialize, minify } from 'miniray'; await initialize({ wasmURL: process.env.WASM_URL ?? '/path/to/miniray.wasm' }); const source = ` struct Uniforms { time: f32; } @group(0) @binding(0) var<uniform> u: Uniforms; @vertex fn main() -> @builtin(position) vec4f { let aspect = 16.0 / 9.0; return vec4f(0.0, 0.0, 0.0, 1.0); } `; const result = minify(source, { minifyWhitespace: true, minifyIdentifiers: true, minifySyntax: true, treeShaking: true, }); console.log(result.code); console.log('Original:', result.originalSize, 'bytes'); console.log('Minified:', result.minifiedSize, 'bytes');

Debug

Known issues

breakinginitialize() must be called before any other function (minify, reflect, validate). Failure to do so will crash at runtime with a panic from the WASM side.

fix

Always await initialize() before using the library.

affects: >=0.1.0

gotchaThe library uses WebAssembly. In browsers, you must either host miniray.wasm yourself or provide a URL. The automatic lookup only works in Node.js (where it uses require.resolve).

fix

For browser usage, either copy miniray.wasm to a public folder or use a CDN. Then pass the URL to initialize({ wasmURL: ... }).

affects: >=0.1.0

gotchaminify() can return errors in the result.errors array. Ignoring them may lead to silent failures.

fix

Always check result.errors after minification.

affects: >=0.1.0

deprecatedThe v1 API (window.miniray in browsers) is deprecated. New code should use the ESM imports.

fix

Use import { initialize, minify } from 'miniray' instead of relying on the global.

affects: <0.2.0

gotchaIn Node.js, the require() version still works, but if using ES modules (type: module in package.json), require is not available. Use import instead.

fix

If your project uses ES modules, use ESM imports: import { initialize, minify } from 'miniray'.

affects: >=0.3.0

Errors

Common errors & fixes

Uncaught (in promise) Error: miniray not initialized. Call await initialize() first.

Called minify() or reflect() before initialize() resolved.

fix

Ensure initialize() is called and awaited before using other API functions.

TypeError: Cannot read properties of undefined (reading 'code')

Result of minify() is undefined because initialization failed or the WASM binary was not found.

fix

Check that the wasmURL is correct and that the binary is accessible. Also ensure initialize() was awaited.

Error: Cannot find module 'miniray'

Package not installed or import path is wrong.

fix

Run npm install miniray (version >=0.3.0) and use proper import syntax.

WebAssembly.instantiate(): expected magic word 00 61 73 6d

The wasmURL points to a non-WASM file (e.g., a text file or wrong path).

fix

Ensure the URL points to the actual miniray.wasm binary file.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

3 hits · last 30 days

claudebot

Resources

githubhttps://github.com/HugoDaniel/miniray ↗

packageminiray ↗

homepagehttps://github.com/HugoDaniel/miniray ↗