vgpu

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. .wgsl files import and export like TypeScript modules, and reflection keeps binding names, types, and layouts correct without hand-written declarations.
• One Gpu context. 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 publishes agents.md and llms.txt for LLM consumption.

View full documentation and examples on vgpu.sh.

Install

pnpm add vgpu
pnpm add -D @webgpu/types

Quick Start

import { 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.

Node quick start

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 modules with typed imports

.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.

Documentation

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 effect

Agent resources

vgpu 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-cwd

Contributing

See CONTRIBUTING.md for the development setup, bundle budgets, and release flow.

License

MIT — see LICENSE.