# vgpu

> A modular TypeScript WebGPU library for building cross-runtime shader applications in browsers, headless Node.js, and CI pipelines, designed for both developers and coding agents.

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.

## Features
- Typed WGSL shader imports like TypeScript modules
- Single Gpu context with no hidden global state
- Cross-runtime: browser, headless Node.js (Dawn), and mock adapter
- Automatic WGSL binding reflection — no manual declarations
- Build-time import graph resolution and dead-code pruning
- Explicit frame/pass rendering model
- CLI for docs, examples, WGSL validation, and runtime diagnostics
- MCP endpoint for agent integration
- llms.txt and agents.md for LLM consumption
- Headless rendering for images, video, and CI snapshots
- Standard WGSL utility library (math, color, noise, hash)
- 25 KB gzipped budget enforced in CI
- OpenAPI 3.1 Examples discovery API
- Deterministic mock adapter for unit tests

## Integrations
WebGPU, Node.js, Dawn (WebGPU native backend), ONNX Runtime Web, Vercel AI SDK, Vercel AI Gateway, Vercel Sandbox, Vercel Workflows, MCP (Model Context Protocol), npm, TypeScript, Next.js, CI/CD pipelines

## Platforms
WEB, CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Version
v0.3.1

## Links
- Website: https://vgpu.sh
- Documentation: https://vgpu.sh/docs
- Repository: https://github.com/vercel-labs/vgpu
- EveryDev.ai: https://www.everydev.ai/tools/vgpu