vgpu

vgpu is an open-source TypeScript library for WebGPU maintained by Vercel under the MIT License. It lets developers write modular WGSL shaders once and run them across interactive browser canvases, headless Node.js rendering, image and video export, and automated CI test suites — all through a single composable API. The project is developed in the open at vercel-labs/vgpu on GitHub and published as the vgpu package on npm.

What It Is

vgpu is a cross-runtime WebGPU rendering library that treats WGSL shader files like TypeScript modules. Its core job is to eliminate the friction of writing GPU code that works in multiple environments: the same shader compiles and runs in a browser canvas, a headless Dawn-backed Node.js process, and a deterministic mock adapter for unit tests. The library resolves WGSL import graphs at build time, reflects binding names and layouts automatically, prunes unused declarations, and emits compact shader source — a complete fullscreen effect ships in 25 KB gzipped, a budget enforced in CI.

Architecture and Package Structure

vgpu is a monorepo with a layered package design:

• vgpu — the public main API: init, draw, compute, effect, frame, bundle, target, uniforms, plus scene and core subpaths.
• @vgpu/cli — the vgpu command-line binary for docs, shader validation (check), and runtime diagnostics (doctor).
• @vgpu/core — low-level WebGPU wrappers (Device, Buffer, Texture, bind groups).
• @vgpu/wgsl — turns .wgsl files into JS modules and resolves WGSL-to-WGSL imports before bundling.
• @vgpu/wgsl-std — standard WGSL utility modules (math, color, sampling, noise, hash).
• @vgpu/adapter-node — Dawn-backed adapter used by vgpu/node.
• @vgpu/adapter-mock — deterministic mock adapter used by vgpu/mock for tests and CI.

The single Gpu context returned by init() is passed explicitly to every entry point — there is no hidden global state.

Agent-Ready Design

vgpu is explicitly built to be operated by coding agents as well as human developers. The CLI exposes docs, examples, WGSL validation, and runtime diagnostics so agents can access them without a browser:

• npx vgpu docs — read the API reference from the terminal
• npx vgpu examples — search and pull reference examples locally
• npx vgpu check — validate WGSL shader source
• npx vgpu doctor — diagnose the runtime environment

The project publishes agents.md, llms.txt, and llms-full.txt at vgpu.sh for LLM consumption, and exposes a tokenless read-only Examples discovery API described by an OpenAPI 3.1 spec. An MCP endpoint at https://vgpu.sh/api/mcp connects agents to documentation and verified examples, and a local stdio MCP server can be run with npx vgpu mcp for package-versioned offline access. vgpu is also listed in the Vercel Agent Stack alongside AI SDK, AI Gateway, Sandbox, and Workflows.

Multi-Runtime Rendering Workflow

The library's rendering model is explicit rather than scene-graph-based. frame(gpu, (f) => f.pass(target, effect)) makes passes, clears, and draws explicit calls. Targets can be a browser canvas surface, a headless RGBA texture, an image file, or a video output. The same shader code path runs across all of them. For CI, vgpu renders a headless frame, compares a snapshot, and reports pass/fail — enabling GPU rendering tests in automated pipelines without a display.

Update: v0.3.1

The latest release is v0.3.1, published on 2026-08-26. The repository was created in May 2026 and has seen active development, with the last push on 2026-08-28. The project has accumulated 823 stars and 31 forks on GitHub. Product direction signals continued investment in agent tooling, MCP integration, and cross-runtime rendering parity.