vgpu is a TypeScript library for WebGPU: typed shader imports, a tiny gpu-first API, and the same code running in the browser, headless Node, and your test suite.
- Typed WGSL imports.
.wgslfiles import and export like TypeScript modules, and reflection keeps binding names, types, and layouts correct without hand-written declarations. - One
Gpucontext.init()returns a single handle; every entry point (draw,effect,frame,surface,target, ...) takes it as its first argument. No hidden global state. - Small by design. Unused declarations are pruned before minification, and a complete fullscreen effect ships in 25 KB gzipped — a budget enforced in CI.
- Multi-runtime by default. One public API surface across the browser, headless Node (
vgpu/node, Dawn-backed), and a deterministic mock (vgpu/mock) built for tests and CI. - Explicit frames.
frame(gpu, (f) => f.pass(target, effect))— passes, clears, and draws are explicit calls, never implicit scene-graph state. - Agent-ready. Docs, the example gallery, and shader validation all run from the CLI (
npx vgpu docs,npx vgpu examples,npx vgpu check), and vgpu.sh publishesagents.mdandllms.txtfor LLM consumption.
View full documentation and examples on vgpu.sh.
pnpm add vgpu
pnpm add -D @webgpu/typesimport { clock, init, effect, frameLoop, surface } from "vgpu";
import waveShader from "./wave.wgsl";
const gpu = await init();
const canvasSurface = surface(gpu, canvas, { dpr: [1, 2] });
const wave = effect(gpu, waveShader, { set: { speed: 2 } });
const time = clock(gpu);
frameLoop(gpu, (frame) => {
wave.set({ time: time.time });
frame.pass(canvasSurface, wave);
});In this example, init() acquires an adapter and device and returns the single Gpu context; every other entry point takes it as its first argument. surface wraps the canvas as a render target and keeps its size current, clamping the device-pixel ratio between 1 and 2. effect compiles the shader into a fullscreen effect whose uniforms are addressed by their WGSL names through set() — writes land immediately, so the loop only sets what changes each frame. clock provides frame time, and frameLoop runs the callback once per frame, where frame.pass draws the effect into the surface.
The same API runs headless, against a Dawn-backed device:
import { draw, frame, init, target } from "vgpu/node";
import triangleShader from "./triangle.wgsl";
const gpu = await init();
const colorTarget = target(gpu, { size: [256, 256], format: "rgba8unorm" });
const triangle = draw(gpu, { shader: triangleShader });
frame(gpu, (f) => f.pass(colorTarget, triangle));
const pixels = await colorTarget.read();
gpu.dispose();vgpu/mock swaps in a deterministic software adapter for the same code, so tests never need a GPU.
.wgsl files import and export like TypeScript modules. @vgpu/wgsl-std ships reusable declarations (hash, noise, color, sampling, ...) as named exports, and any .wgsl file can export its own fn, struct, or const for other shaders to import:
// grain.wgsl
import { hash2 } from "@vgpu/wgsl-std/hash";
export fn grain(uv: vec2f, time: f32) -> f32 {
return hash2(uv * time).x;
}Imports resolve at build time through typed WGSL reflection — no codegen step and no manual binding declarations to keep in sync.
Full documentation lives on vgpu.sh. Start with Getting started, then the performance playbook for the defaults (bundles, target pre-warm, in-place set(), instancing, ping-pong, MSAA/depth) that shader authors should reach for from day one. Interactive examples run in the browser, and their source is what vgpu examples serves.
The same guides and API reference also ship inside the package and run fully offline through the CLI:
npx vgpu docs cat getting-started.md
npx vgpu docs find effectvgpu is built to be operated by coding agents as well as people. The example gallery is searchable from the CLI, and any example's complete source can be copied locally without cloning the repository:
npx vgpu examples search "raymarching"
npx vgpu examples pull <id> --out ./example- Agent readiness manifest — how agents should discover and use vgpu
- llms.txt and llms-full.txt — documentation index and full export for LLMs
- Examples discovery API — tokenless and read-only, described by OpenAPI
- MCP guide — connect agents to the public read-only endpoint at
https://vgpu.sh/api/mcp, or run local stdio for package-versioned docs and opt-in example downloads
npx vgpu mcp
npx vgpu mcp --project-from-cwdThis is a monorepo. The public entry point is vgpu; everything else backs it or ships independently.
| Package | What it is |
|---|---|
vgpu |
Public main API: init, draw, compute, effect, frame, bundle, target, uniforms, plus scene and core subpaths. |
@vgpu/cli |
The vgpu command-line binary: docs, shader check, doctor, and Dawn/software-renderer setup. |
@vgpu/core |
Low-level WebGPU wrappers (Device, Buffer, Texture, bind groups) behind vgpu/core. |
@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. |
@vgpu/render |
Slim edit/inspect/utils/perf helpers outside the main rendering surface. |
See CONTRIBUTING.md for the development setup, bundle budgets, and release flow.
MIT — see LICENSE.