@vgpu/wgsl weekly downloads statistics

@vgpu/wgsl

@vgpu/wgsl turns WGSL files into JavaScript shader-source modules and resolves WGSL-to-WGSL imports before bundling. It includes a resolver/runtime, webpack and Vite integrations, and a TypeScript ambient-types sub-export for import shader from "./shader.wgsl".

The resolver preserves shader entry-point names for WebGPU pipeline creation while mangling non-entry helpers and imports to avoid cross-module symbol collisions. Loader integrations also wire transitive .wgsl imports into bundler watch/HMR systems.

Installation

TypeScript setup

Add a project .d.ts file (for example wgsl-env.d.ts):

Or add the package type to tsconfig.json:

This is required for TypeScript to accept .wgsl imports. If you cannot use the sub-export, a local fallback is:

Bundler integrations

Webpack 5

Recommended rule:

Verbose/options form (advanced):

minify defaults to false; set it to true for the production preset: strip comments/whitespace and safely shorten supported private identifiers. Use { minify: { whitespace: true } } for whitespace-only output.

Vite 5+

Pass wgslVitePlugin({ minify: true }) for the production preset: strip comments/whitespace and safely shorten supported private identifiers. Use { minify: { whitespace: true } } for whitespace-only output.

Next.js / Turbopack (Next >= 15.5)

Recommended string form:

Verbose/options form (advanced; object loaders require options by the Next TypeScript type):

Use legacy experimental.turbo.rules on older Next 15.0-15.2 apps. The as: "*.js" mapping is required because Turbopack's webpack-loader bridge expects loaders to return JavaScript.

WGSL syntax

WGSL modules can import named exports from other WGSL files:

Imported files export normal WGSL declarations:

See examples/next-wgsl/app/*.wgsl and packages/wgsl/tests/*.test.ts for more examples.

Mangling and entry-point preservation

Non-entry helpers and imported symbols may be renamed to _vgsl___ to avoid collisions between modules. WebGPU entry-point functions annotated with @vertex, @fragment, or @compute are preserved, so pipeline creation keeps working:

Bindings and override constants are likewise exposed by their shader-visible names; when a reflected item needs a generated name, use its mangledName field.

Reflection API

resolveShader() returns { wgsl, deps, cacheKey, ast, sourceMap, diagnostics, reflection }. reflectSource(wgsl, path?) returns the same frozen ReflectionFacade shape for a single raw WGSL string without resolving imports; if the source contains WGSL imports it throws and points callers to resolveShader().

Reflection currently exposes:

| Field | Description |

| reflection.entryPoints | { name, mangledName, stage, workgroupSize? } for @vertex, @fragment, and @compute functions. | | reflection.bindings | { group, binding, name, type, kind, addressSpace?, access?, struct?, layout?, bindingLayout? } for discovered resources, including BGL-precise layouts. | | reflection.overrides | { name, mangledName, defaultValue? } for override constants. | | reflection.featuresRequired | Feature names from enable ...; directives. | | reflection.structs / reflection.aliases | Reflected host-visible type declarations with original and mangled names. | | reflection.hostShareableLayouts | Naga-standard host-shareable layouts for uniform/storage resources. |

Minify option

resolveShader, @vgpu/wgsl/loader-webpack, @vgpu/wgsl/loader-vite, and transformWgsl accept minify?: boolean | { whitespace?: boolean; identifiers?: "none" | "safe" }. The default is false, preserving previous output.

• minify: true is the production preset: { whitespace: true, identifiers: "safe" }. • Object form defaults to whitespace minification on and identifier renaming off: { whitespace: true, identifiers: "none" }. • Use { minify: { whitespace: true } } for whitespace-only output. • Use { minify: { identifiers: "safe" } } for whitespace plus safe identifier shortening.

identifiers: "safe" is AST/scope-aware and intentionally narrow in this release. It can shorten function-local let/var/const, function parameters, for-initializer locals, and resolver-generated private helper functions named like _vgsl___name when analysis proves they are safe. If the analyzer is unsure, it conservatively preserves names instead of renaming them. The feature has no runtime dependency.

The minifier never renames entry points; resources/bindings/uniform/storage/texture/sampler declarations; overrides or override references; struct/type names; struct fields; import/export/reflection-visible names; attributes, builtins, or WGSL predeclared names. Existing import flattening and collision-avoidance mangling is unchanged.

When validation is enabled, resolveShader() validates the unminified emitted WGSL first so diagnostics map to authored modules. If identifier minification is enabled, it also validates the final minified WGSL. Source maps for compact output and struct-field renaming are deferred.

HMR behavior

Transitive .wgsl imports are registered with each bundler's watch graph:

• Webpack: the loader calls this.addDependency() for resolved dependencies. • Vite/Rollup: the plugin calls this.addWatchFile(). • Turbopack: the webpack-loader bridge tracks patched async fs.readFile calls; the resolver uses fs/promises.readFile so transitive imports are intercepted. resolveShader() does not keep a stale entry-level resolveCache, so reloads re-read changed imports.

API reference

| Export | Purpose |…

Description from the npm listing.