vgpu

Vercel Labs' 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." MIT, 716★ / 25 forks, created 2026-05-05, last push 2026-08-28, 1,037 commits. Docs and examples at vgpu.sh. Shared via Telegram, routed here by the hub. Metadata read from the GitHub and npm APIs on 2026-08-28.

Pre-1.0 and moving fast: first npm publish 2026-05-26, twenty versions since, latest 0.3.1 (2026-08-26). Four months old at ingest.

Not an engine, and that is the point

Every web-graphics page in this spoke so far is a scene-graph library or an engine — Three.js, Babylon.js, PixiJS, PlayCanvas. vgpu sits below them and says so in its design rules:

frame(gpu, (f) => f.pass(target, effect)) — passes, clears, and draws are explicit calls, never implicit scene-graph state.

There is one Gpu context returned by init(), passed explicitly to every entry point (draw, compute, effect, frame, bundle, target, uniforms), with no hidden globals. A scene subpath exists, but the default posture is that the caller owns the frame. That makes it the first source here on the layer between raw WebGPU and an engine, and it fills the gap the webgpu page described as a bare backend under the engines.

The monorepo splits accordingly: vgpu (public API), @vgpu/core (Device/Buffer/Texture wrappers), @vgpu/wgsl (the shader build step), @vgpu/wgsl-std (math, colour, sampling, noise, hash), @vgpu/adapter-node, @vgpu/adapter-mock, @vgpu/render, @vgpu/cli.

The three-runtime claim, and why the mock matters

One API surface across the browser, headless Node backed by Dawn (vgpu/node), and a deterministic mock adapter (vgpu/mock) so tests run with no GPU present. The Node path reads pixels back off a render target:

frame(gpu, (f) => f.pass(colorTarget, triangle));
const pixels = await colorTarget.read();

Rendering code that runs in CI without hardware is unusual in this corpus. Every engine here is tested by running the editor; a graphics library that ships a software adapter as a first-class export is making testability an API-design decision rather than an infrastructure problem.

Shaders as modules

.wgsl files import and export like TypeScript modules — a file can export fn, export struct, export const, and import from @vgpu/wgsl-std. Resolution happens at build time through typed WGSL reflection, so binding names, types and layouts come from the shader rather than from hand-written declarations, with no codegen step to keep in sync. That is the piece a shader author would notice first, and it is what the @vgpu/wgsl package exists to do.

The byte budget is enforced machinery, not a slogan

The README claims a complete fullscreen effect at 25 KB gzipped, "a budget enforced in CI." The enforcement is real and reading it is more informative than the number. scripts/lib/bundle-budgets.mjs sets budgets as multiples of 512 bytes, derived as the smallest 512 B step above the measured size, and splits artifacts into two audiences: client is a hard gate and the default for anything unclassified, while tooling allows 5% growth with a warning instead of a failure. Unclassified means gated — the default is the strict one.

This is the leanness thesis in a different medium. Godot's 164 MB against Unreal's 21 GB is a size difference discovered after adoption; vgpu makes the size a build-breaking assertion in the repository, which is the mechanism the webperf adjacency has been describing without a game example. Cross-spoke: ../webperf-wiki owns performance budgets as a front-end practice.

The budget also moves. A commit on 2026-07-26 raised the vgpu entrypoint bundle budgets to 45 KB gzip and the CLI pack-size budget to 800 KB. Those are different artifacts from the 25 KB fullscreen-effect figure, so it is not a contradiction — but it does show what a budget in a pre-1.0 library is: a ratchet the maintainers reset deliberately, recorded in history, rather than a fixed ceiling.

Built to be driven by an agent, from day one

vgpu's agent surface is not a plugin over an editor. It is the documentation and example system itself, and it ships in the package:

npx vgpu docs cat <file> / docs find <term> — the full guides and API reference offline, from the installed package.
npx vgpu examples search "raymarching" / examples pull <id> --out ./example — the gallery is searchable and copyable without cloning.
npx vgpu check (shader validation) and vgpu doctor (Dawn / software-renderer setup).
npx vgpu mcp, or --project-from-cwd for package-versioned docs; a public read-only MCP endpoint at https://vgpu.sh/api/mcp.
Published manifests: agents.md, llms.txt, llms-full.txt, an examples-discovery API described by OpenAPI and documented as tokenless and read-only.

The manifest tells agents to prefer the CLI for discovering examples, to favour the public MCP server for docs and example discovery, and to verify SHA-256 values before using any downloaded artifact. That is the same instinct as the token-gated localhost rule the engines arrived at on engine-agent-surface, applied to a supply chain rather than to a live editor.

And the workspace package.json carries agent-evals scripts (s2-gradient, n1-hero-shader, view-image-smoke) — the project runs coding agents against itself as a test task. Whatever else is marketing, that one is a build step.

Recorded, not asserted: an agent is a listed contributor

Contributor commit counts from the GitHub API on 2026-08-28: matiasngf 1,014, claude 21, dev-tmg 1, vercel[bot] 1. The 21 are authored Claude <noreply@anthropic.com>, and their subjects are ordinary maintenance — raising the bundle budgets, rewriting docs for a new pipeline.

No policy is stated in the repository about agent contributions, and none is claimed here. The fact is on this page because the spoke holds the opposite policy in writing: the Godot Foundation auto-bans autonomous agents and "vibe coding" from its GitHub org. Two projects on the same continent of tooling, one banning agent commits and one merging twenty-one of them, is a comparison the corpus can now make from primary evidence on both sides.

What is not here

No benchmark against Three.js or Babylon.js — no frame times, no draw-call counts, nothing that would place it on the spoke's performance axis. The repository's own description advertises "GPU tensors, neural networks, and math viz" and the README barely touches them, so the compute half is claimed rather than shown. And at four months old with one dominant author, the maintenance question that decides whether a library is usable in two years has no evidence either way.

webgpu · three-js · babylonjs · pixijs · playcanvas · engine-agent-surface · godot-contribution-policy-2026 · vercel · synthesis