Registry / web-framework / wgsl_reflect

wgsl_reflect

JSON →
library1.2.3jsnpmunverified

wgsl_reflect is a JavaScript and TypeScript library designed for parsing and reflecting WebGPU Shading Language (WGSL) shaders. It provides comprehensive static analysis of WGSL code, extracting critical metadata such as bind group layouts, resource bindings, uniform buffer structures, and the members, types, sizes, and offsets of these structures. This functionality is particularly valuable for WebGPU developers as the standard WebGPU API lacks built-in shader reflection capabilities, making dynamic buffer creation and data layout challenging. The library is actively maintained, with version 1.2.3 being the current stable release, and it generally follows semantic versioning. It serves as an essential tool for dynamically inspecting shader interfaces, streamlining the setup of GPU resources from JavaScript, and integrating with higher-level WebGPU frameworks.

npm install wgsl_reflect
INSTALL
IMPORT
SIG · WGSL_REFLECT
W
wgsl_reflect
web-frameworkjavascriptv1.2.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

WgslReflect
import { WgslReflect } from 'wgsl_reflect/wgsl_reflect.module.js';
import { WgslReflect } from 'wgsl_reflect'; import WgslReflect from 'wgsl_reflect/wgsl_reflect.module.js'; const WgslReflect = require('wgsl_reflect/wgsl_reflect.module.js');
The library explicitly uses an ESM module path (`.module.js`). Direct import from the package root or using CommonJS `require()` might not work as expected or requires specific bundler configurations. It is a named export, not a default export.
ResourceType
import { ResourceType } from 'wgsl_reflect/wgsl_reflect.module.js';
Enum for identifying different types of shader resources (Uniform, Storage, Texture, Sampler, StorageTexture).
VariableInfo
import { VariableInfo } from 'wgsl_reflect/wgsl_reflect.module.js';
Interface/class describing information about a reflected shader variable, including its name, type, group, binding, and resource type.

This quickstart demonstrates how to parse a WGSL shader, extract its uniform buffer layouts, individual resource bindings, and entry point functions. It prints detailed information about the uniform variables, their struct members, and the shader's entry points, which is crucial for setting up WebGPU pipelines dynamically.

import { WgslReflect } from 'wgsl_reflect/wgsl_reflect.module.js'; const shaderCode = ` struct ViewUniforms { viewProjection: mat4x4<f32>; }; struct ModelUniforms { model: mat4x4<f32>; color: vec4<f32>; intensity: f32; }; @group(0) @binding(0) var<uniform> viewUniforms: ViewUniforms; @group(0) @binding(1) var<uniform> modelUniforms: ModelUniforms; @group(0) @binding(2) var u_sampler: sampler; @group(0) @binding(3) var u_texture: texture_2d<f32>; @vertex fn vs_main(@builtin(vertex_index) in_vertex_index: u32) -> @builtin(position) vec4<f32> { _ = in_vertex_index; // Use to avoid unused variable warning _ = u_sampler; _ = u_texture; return viewUniforms.viewProjection[0]; } @fragment fn fs_main(@builtin(position) fragCoord: vec4<f32>) -> @location(0) vec4<f32> { _ = fragCoord; return modelUniforms.color * modelUniforms.intensity; } `; const reflect = new WgslReflect(shaderCode); console.log('--- Reflected Uniforms ---'); reflect.uniforms.forEach(u => { console.log(` Name: ${u.name}, Group: ${u.group}, Binding: ${u.binding}, Size: ${u.size} bytes`); }); const viewUniformsStruct = reflect.getStructInfo('ViewUniforms'); if (viewUniformsStruct) { console.log('\n--- ViewUniforms Struct Members ---'); viewUniformsStruct.members.forEach(m => { console.log(` Name: ${m.name}, Type: ${m.type.name}, Offset: ${m.offset}, Size: ${m.size} bytes`); }); } console.log('\n--- Entry Points ---'); for (const entryType in reflect.entry) { reflect.entry[entryType].forEach(e => console.log(` ${entryType}: ${e.name}`)); } // This quickstart demonstrates how to parse a WGSL shader, extract its uniform buffer layouts, // individual resource bindings, and entry point functions. It prints detailed information // about the uniform variables, their struct members, and the shader's entry points, // which is crucial for setting up WebGPU pipelines dynamically.
Debug
Known issues
breakingThe WGSL specification is still evolving. Major changes to the WGSL language syntax or semantics might cause parsing failures or incorrect reflection results in `wgsl_reflect` if the library is not updated to support the new specification. Always ensure your library version is compatible with the WGSL version you are using.
fix
Regularly update `wgsl_reflect` to the latest version via `npm install wgsl_reflect@latest` to ensure compatibility with recent WGSL specification changes. Report any parsing issues with valid WGSL to the library's GitHub repository.
affects: All versions
gotchaWhen importing `WgslReflect` in an ESM context, the explicit full path `wgsl_reflect/wgsl_reflect.module.js` is required. Attempting to import directly from the package root (e.g., `from 'wgsl_reflect'`) or using CommonJS `require()` syntax will lead to module resolution errors or runtime failures.
fix
Always use `import { WgslReflect } from 'wgsl_reflect/wgsl_reflect.module.js';` for ESM imports. If using CommonJS, consider transpilation or a bundler that correctly handles ESM packages.
affects: >=1.0.0
gotchaWhile robust, `wgsl_reflect` might occasionally encounter difficulties with highly experimental or non-standard WGSL syntax, or specific edge cases in parsing complex type definitions (e.g., deeply nested generics or arrays of structs). This could lead to incomplete or incorrect reflection data.
fix
Simplify complex WGSL constructs where possible if encountering parsing issues. Refer to the library's documentation and GitHub issues for known limitations or workarounds. Validate reflection output against expected shader behavior.
affects: All versions
Errors
Common errors & fixes
Error: Cannot find module 'wgsl_reflect'
Incorrect import path for the ESM module, omitting the explicit `.module.js` suffix or trying to import from the package root.
fix
Change the import statement to `import { WgslReflect } from 'wgsl_reflect/wgsl_reflect.module.js';`
TypeError: WgslReflect is not a constructor
Attempting to import `WgslReflect` as a default export when it is a named export.
fix
Ensure `WgslReflect` is imported as a named export: `import { WgslReflect } from 'wgsl_reflect/wgsl_reflect.module.js';` (note the curly braces).
Syntax Error: Unexpected token
The provided WGSL shader code contains a syntax error, uses a WGSL feature not yet supported by the `wgsl_reflect` parser, or is malformed.
fix
Review the WGSL shader code for syntax errors. Ensure the `wgsl_reflect` library is up-to-date. If the WGSL is valid according to the latest spec but still fails, report an issue to the library's maintainers.
Upgrade
Version history
1.2.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
28 hits · last 30 days
node
22
Resources
wgsl_reflect — npm install wgsl_reflect · libregistry