vgpu: the default branch is canary, Node 22 has an upper bound, and the docs search for an example that is not there
Modular cross-runtime WebGPU library for shaders, 3D scenes, GPU tensors, neural networks, and math viz
At a glance
- What is it?
- A TypeScript WebGPU library with typed shader imports that runs in a browser, in headless Node against a Dawn device, and in a deterministic mock, with a 25 KB size budget enforced in CI. Its example gallery command demonstrates a search for a raymarching example the repository does not contain.
- Who is it for?
- vgpu is a well-designed library for anyone who wants shaders and a renderer with one typed API across three runtimes, and the mock adapter plus snapshot checking is the most reusable idea in it, since it is how you get a GPU renderer into continuous integration at all. Three things to know.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- vercel-labs/vgpu2,666 ★ · +411
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| vercel-labs/vgpu | 2.3k | 2.7k |
411 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The gallery command searches for an example the repository does not have
The agent resources section teaches you to search the example gallery from the command line, and the demonstration is a search for one term: raymarching. Now count the example directories at the repository root. There are fifteen, and they cover a fullscreen effect, a sharing setup, shared uniforms, resource fixes, a scene, high dynamic range with post-processing, ping-pong buffers, bundles, group claims, compute work, scheduling and resize, a headless case, a fluid validation, and two directories named after other projects entirely. None of them is a raymarcher. So the first thing a reader is shown, the one command that makes the gallery feel searchable, points at nothing. The numbering also starts at the second entry and runs to the thirteenth, so the first example in the series is not in the tree under that naming scheme, and two of the fifteen directories are named for integrations rather than features.
pnpm add vgpu
pnpm add -D @webgpu/typesTwo package names point at cross-wired directories
The packages table has eight rows, and two of them are worth reading twice. The row for the package named vgpu links to a readme inside a directory called vgpu-api. The row for the command line binary, whose package name has a scope on it, links to a readme inside a directory called vgpu. So the public library lives in the directory named after the API and the command line tool lives in the directory named after the library. That would be a tolerable quirk in a small monorepo, but this table is the first thing a reader uses to work out what to install and what it imports, and the two entries are the two most important ones. The naming inside the table helps a little: the binary is called vgpu on your command line even though its package is scoped, which at least explains why the quick start installs one package and the agent section invokes a differently named one.
import { clock, init, effect, frameLoop, surface } from "vgpu";
import waveShader from "./wave.wgsl";The description promises tensors and networks, the page documents a renderer
The repository's one-line description lists five things: shaders, three-dimensional scenes, GPU tensors, neural networks, and maths visualisation. The readme's feature list and its package table cover the first two. There is a scene subpath and a scene type-check project in the build scripts, so scenes are real, and everything else in the documentation is about rendering: surfaces, targets, bundles, passes, ping-pong buffers, multi-sample rendering, draw and compute entry points. There is no tensor API described, no neural network layer, and no maths visualisation anywhere in the text. That is not necessarily a promise being broken, since a description can be a direction of travel, but it does mean a reader deciding whether this library is a maths and machine learning toolkit will find nothing to confirm it, and should decide on the rendering surface instead.
Node 22 with an upper bound, and a package manager pinned to a major behind
The workspace manifest is unusually restrictive in two fields. The engine field is not a floor but a bracket: a lower bound of the twenty-second major and an upper bound excluding anything in the twenty-third, which means the only supported runtime is one major version of Node. For a library whose headline feature is running the same code in a browser, where there is no Node version at all, that is an unusual constraint to impose on the server-side path. The package manager field pins a specific version inside the ninth major of pnpm, and the documented install path is pnpm only, with no npm or yarn instruction anywhere on the page even though the package is published on the npm registry and one of the badges points there. The WebGPU type definitions are installed as a development dependency, with an ambient declaration file at the repository root, which is the standard way to make the browser's own types visible to the compiler without shipping them.
Eight separate type-check projects and an inline script in the build
The build file is the best map of how much of this API is hand-written. The typecheck script runs the compiler once, then runs eight more compiler invocations against eight different project files, covering create-sampler types, general types, uniform types, three separate scene type surfaces, the documentation site's examples, frame types, and device-loss types. A generated codebase would not need that; eight hand-maintained type surfaces is what a hand-typed API costs. The build script has its own surprise: after the compiler runs, it invokes a one-line node command with a filesystem copy expression inline, alongside two proper script files, to place a type declaration into the output directory. That is the kind of step that breaks on a different shell, and it is why the repository carries a patches directory. The release chain is longer still: a finalize step that runs the migrations tool, then two separate documentation generators, then a migration check in release mode.
"release:finalize": "node scripts/migrations.mjs finalize && pnpm --filter @vgpu/cli generate:docs && pnpm --filter @vgpu/cli generate:docs:geistdocs && pnpm migrations:check --release"How a GPU renderer gets into continuous integration
The answer is three packages and three scripts, and it is the most reusable part of the design. There is a deterministic mock adapter, exposed as a subpath, which substitutes a software adapter so that the same code runs without a GPU; the readme says tests never need one. There is a separate Dawn-backed adapter for the headless Node path, which is the real device and the slow one. And there is a snapshot script with a check mode and an update mode, so rendered output is compared rather than asserted by hand. The test scripts then divide along exactly that line: the fast target runs the compiler over the mock adapter, the core wrappers, the shader tooling, the render helpers and the scripts, while deliberately leaving out both the Node adapter and the main API package, and a separate target runs everything inside Docker through a shell script under an infrastructure directory. So the split between what is cheap to test and what needs a device is written into the build file rather than left to judgement.
A tokenless public endpoint, and a skill that refuses to carry an API reference
The agent integration is unusually open, and the two halves are worth separating. The public side: a model context protocol endpoint on the documentation site that is tokenless and read-only, an example discovery API described by an OpenAPI document, and machine-readable documentation indexes in two forms, one short and one full. Nothing there needs a credential, which is defensible for documentation but means anyone can enumerate the gallery and read the guides without registering. The installed side does something smarter. The skill offered to agents with skill support is described as a thin documentation router that deliberately contains no versioned API reference at all, and instead queries the documentation bundled with the version of the package installed in the project. That solves the problem every agent-facing skill has, where the instructions describe an API the project no longer has, by refusing to hold one. The package also ships its guides offline, with commands to read and search them locally.
npx vgpu mcp
npx vgpu mcp --project-from-cwd25 KB is the only number on the page, and CI enforces it
One claim in the feature list is quantitative: a complete fullscreen effect ships in twenty-five kilobytes gzipped, and unused declarations are pruned before minification to get there. What makes it worth repeating is that the page says the budget is enforced in continuous integration. That is the difference between a size claim and a size constraint, and it means the pruning step is not an optimisation someone did once. The rest of the design follows the same discipline. One context handle, passed explicitly to every entry point, with no hidden global state. Frames, passes, clears and draws as explicit calls, never implicit scene-graph state. And a performance playbook that names the six things shader authors should reach for on day one, which is a library telling you its defaults are the fast path rather than leaving you to discover them. The root directory shows the same instinct in its structure, with two near-identically named tool directories and both an experiments and an examples directory.
Editorial conclusion
vgpu is a well-designed library for anyone who wants shaders and a renderer with one typed API across three runtimes, and the mock adapter plus snapshot checking is the most reusable idea in it, since it is how you get a GPU renderer into continuous integration at all. Three things to know. The engine field caps Node at version 22, so the toolchain will not install on a newer runtime without a change. The docs example demonstrates searching the gallery for a raymarching example that is not in the tree. And the description advertises GPU tensors, neural networks and math visualisation that the documentation never describes, so judge the scope from the API table rather than the summary.
Frequently asked questions
What is the vgpu library?
It is a TypeScript library for WebGPU with typed shader imports, a single context handle that every entry point takes as its first argument, and no hidden global state. The same public API runs in a browser, in headless Node against a Dawn-backed device, and against a deterministic mock adapter.
How do you run vgpu outside a browser?
You import from the node subpath, which uses a Dawn-backed adapter and exposes draw, frame and target entry points, so a shader can be rendered into a target and its pixels read back. The same code can also run against a deterministic mock adapter, so tests never need a GPU.
How large is the vgpu bundle?
The page states that a complete fullscreen effect ships in 25 KB gzipped, with unused declarations pruned before minification, and that this budget is enforced in continuous integration.
How does vgpu handle shader files?
Shader files import and export like TypeScript modules, and imports resolve at build time through typed reflection with no codegen step and no hand-written binding declarations. A standard library package ships reusable declarations, and uniform values are addressed by their names as written in the shader.
Does vgpu offer an MCP server or agent integration?
Yes. There is a public tokenless read-only endpoint on the documentation site, a local server you can start with the command, an OpenAPI-described example discovery API, machine-readable documentation indexes, and a skill that deliberately contains no versioned API reference and instead queries the documentation bundled with the installed package version.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vercel-labs-vgpu)Star history chart for your README
[](https://hysenlabs.com/projects/vercel-labs-vgpu)Was this useful?