wgsl-plus

library1.0.1jsnpmunverified

WGSL-Plus (v1.0.1) is a comprehensive WGSL shader toolchain providing preprocessing with C-style macros (#define, #ifdef, #include), minification, obfuscation, and pretty-printing for WebGPU shaders. It supports conditional compilation, file linking, and multiple output formats (WGSL, SPIR-V via naga, GLSL, MSL). Unlike basic formatters, it adds macro expansion and obfuscation suitable for production builds. Updated irregularly on GitHub.

devops testing

npm install wgsl-plus

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WGSL-PLUS

wgsl-plus

devopsjavascriptv1.0.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.

compile

✓ import { compile } from 'wgsl-plus'

✗ const compile = require('wgsl-plus').compile

ESM-only package; CommonJS require requires explicit .default for the default export.

prettify

✓ import { prettify } from 'wgsl-plus'

✗ const { prettify } = require('wgsl-plus')

Named export; CommonJS users must use .default first.

minify

✓ import { minify } from 'wgsl-plus'

✗ import minify from 'wgsl-plus'

Named export, not default.

Compile WGSL source with macros and conditional compilation, outputting formatted WGSL.

import { compile } from 'wgsl-plus'; // WGSL shader source with macros const source = ` #define PI 3.14159 #define USE_LIGHTING fn getColor() -> vec4<f32> { #ifdef USE_LIGHTING return vec4<f32>(1.0, 0.0, 0.0, 1.0); #else return vec4<f32>(0.0, 0.0, 1.0, 1.0); #endif } @vertex fn vs_main(@builtin(vertex_index) idx: u32) -> @builtin(position) vec4<f32> { return vec4<f32>(0.0, 0.0, 0.0, 1.0); } `; const result = compile(source, { obfuscate: false, minify: false, format: 'wgsl' }); console.log(result.code);

Debug

Known issues

breakingv1.0.0 changed the default output from 'pretty' to 'minified' to reduce code size. Pass { minify: false } to preserve formatting.

fix

Add option `minify: false` if you expect readable output.

affects: >=1.0.0

breakingThe API changed from a single `wgslPlus.transform()` to separate `compile()`, `prettify()`, and `minify()` functions in v1.0.0.

fix

Use `compile()` for macro expansion; `prettify()` for formatting; `minify()` for minification.

affects: >=1.0.0

deprecatedThe `obfuscate` option in `compile()` is deprecated in favor of separate `obfuscate()` function (not yet released).

fix

Avoid using obfuscate for now; wait for the dedicated function.

affects: >=1.0.0

gotchaC-style macros in WGSL-Plus use `#` prefix (like C preprocessor) but may conflict with WGSL attributes like `@group`. Macros must be on separate lines before any WGSL code.

fix

Place all `#define` and `#include` lines at the top of the file, before any `@` or `fn` tokens.

affects: >=0.0.0

gotchaWhen using `#include` with relative paths, the base is the current working directory, not the file's location. Use absolute paths or set `cwd` option.

fix

Pass `{ cwd: __dirname }` in the compile options to resolve includes relative to the calling file.

affects: >=0.0.0

Errors

Common errors & fixes

SyntaxError: Unexpected token '#'

WGSL-Plus macro lines are not recognized by the WebGPU native compiler; they must be removed before passing to the GPU, but the error occurs if you pass raw source.

fix

Run the source through `compile()` first, then send `result.code` to the GPU.

Error: #include not found: module.wgsl

The file `module.wgsl` is not in the current working directory or path is relative incorrectly.

fix

Use an absolute path or set `cwd` option: `compile(source, { cwd: __dirname })`.

TypeError: compile is not a function

CommonJS `require('wgsl-plus')` returns the module object, not the named export directly.

fix

Use `const { compile } = require('wgsl-plus');` or `import { compile } from 'wgsl-plus'`.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/JSideris/wgsl-plus ↗

packagewgsl-plus ↗

homepagehttps://jsideris.github.io/wgsl-plus/ ↗