One API spans browser, Node, and deterministic tests
vgpu wraps WebGPU in a TypeScript API built around one Gpu context. Browser code gets a canvas surface, Node code gets a Dawn-backed device through vgpu/node, and test code can swap in vgpu/mock. The mock is deterministic and needs no GPU, which gives application tests a way to exercise shared rendering code in CI. Calls still expose frames, targets, passes, draws, effects, and resource disposal rather than hiding the GPU execution model.
The quick-start fullscreen effect is compact enough to show the design. init() acquires the adapter and device, surface() tracks canvas size within a device-pixel-ratio range, and effect() compiles the imported shader. A clock feeds one changing uniform inside a frame loop. Uniform writes use WGSL names, and each frame states where the pass goes. Developers who dislike implicit renderer state will appreciate that arrangement; scene-engine users may find it low level.
Typed WGSL removes duplicate binding declarations
Shader files can import and export functions, structs, and constants as modules. Reflection carries binding names, data types, and layouts into TypeScript, removing a separate handwritten declaration layer. The package also ships @vgpu/wgsl-std modules for math, color, sampling, noise, and hashes. Imports resolve during the build with no extra code-generation command described in the README. That is vgpu's sharpest argument over a thin wrapper around raw WebGPU.
The public vgpu package exposes drawing, compute, effects, frames, bundles, targets, uniforms, scene helpers, and a lower-level core path. Supporting workspace packages handle the CLI, WGSL transformation, standard shader modules, Node and mock adapters, and extra rendering utilities. Our checkout contained 2,423 files and roughly 146,976 source lines, so the small public vocabulary sits on a substantial monorepo rather than a tiny adapter package.
What happened when we ran it
Our sandbox installed 941 pnpm packages in 41 seconds and occupied 1,905 MB after installation. The build completed successfully in 9 seconds. Tests continued for 129 seconds and exited with code 1: Vitest counted 2,417 passed, 1 failed, and 150 skipped out of 2,568. The repository itself was 67.8 MB before that dependency install.
The log tail identifies the failure as a test exceeding the 30,000 ms timeout. It reports 1 failed test file, 330 passed files, and 25 skipped files out of 356. The supplied tail does not name the timed-out test or explain why it stalled, so blaming graphics hardware, container limits, or application code would be guesswork. The useful result is narrower: commit 2e29a32 built but did not pass its complete suite in our fresh 3-CPU, 8 GB Debian container.
Headless rendering and mocks serve different checks
vgpu/node runs the same public shape against Dawn and can render into an offscreen target whose pixels are readable. That path is relevant for generated images, server graphics, and checks that require a real WebGPU implementation. vgpu/mock instead supplies a deterministic software adapter for tests. The mock can make application behavior reproducible, but it cannot prove that a shader behaves correctly on every browser, driver, or physical GPU. A serious release pipeline needs both kinds of coverage.
The README does not document a WebGL fallback. That is a decisive constraint for products supporting browsers or devices without WebGPU. It also means a team should verify feature availability before initializing the renderer and provide an intentional unsupported-state experience. vgpu's cross-runtime claim concerns several WebGPU environments and its mock; it should not be read as universal browser graphics compatibility.
Agent tooling is useful even without an agent writing shaders
The CLI can search offline documentation, show a named guide, validate shaders, diagnose the environment, and browse or copy examples. The package also provides a local stdio MCP server plus a hosted read-only MCP endpoint for documentation and verified examples. agents.md, llms.txt, and a tokenless examples API give coding agents structured discovery paths. Human developers benefit from the same local, version-matched docs when internet access is unavailable.
Example portability is still being worked through. Release v0.3.1 says it improved examples on macOS and Windows, while issue 383 reports that vgpu examples pull fails on Windows because safe destination storage is unsupported on win32. Issue 384 says documentation search can print paths that the corresponding cat command cannot open. These are tooling defects rather than evidence about rendering correctness, but they affect the agent-friendly workflow the project advertises.
v0.3.1 is moving quickly and still earns its zero-major caution
GitHub showed 938 stars, 44 combined open issues and pull requests, and a last push on August 29, 2026. Release v0.3.1 arrived on August 26 with local and hosted MCP servers, portability work, and recovery for failed WGSL imports. The issue list had same-day reports and pull requests when fetched, which supports an active-maintenance reading. The v0 version and our one timed-out test still argue for pinning the package and testing upgrades.
vgpu is a credible choice when typed WGSL and shared browser, Node, and test code solve an existing engineering problem. The 9-second build and 2,417 passing tests show considerable working surface, while the failed suite prevents a clean bill of health. Prototype one real effect, one headless job, and one mock-based test before committing a renderer architecture to it.