learn-wgpu: A Worked Tutorial for the wgpu Graphics Library

What wgpu Is, and Why the Guide Exists

The introduction starts with the library rather than the tutorial, which is the right order. wgpu is a Rust implementation of the WebGPU API spec, and WebGPU is a specification published by the GPU for the Web Community Group. The aim of the spec is to allow web code access to GPU functions in a safe and reliable manner.

The mechanism is that WebGPU mimics the Vulkan API and translates that down to whatever API the host hardware is using, for example DirectX, Metal or Vulkan. So the same Rust code runs on a Windows machine with a DirectX driver, an Apple machine with Metal, or a Linux machine on Vulkan.

The guide also flags its own moving target. Wgpu is still in development, so some of the documentation is subject to change. That is a real constraint for a tutorial, and it is why the version of wgpu in the workspace dependencies, 30.0, matters.

The other half of the introduction is about Rust. wgpu actually has C bindings to allow you to write C and C++ code with it, as well as use other languages that interface with C, but it is written in Rust and it has convenient Rust bindings that do not have to jump through any hoops.

The prerequisites are stated too. You should be fairly familiar with Rust before using this tutorial, since the guide does not go into much detail on Rust syntax, and you should also be familiar with Cargo.

Four Tutorial Tracks in One Cargo Workspace

The repository is organised as a Cargo workspace whose members are the tutorial's code, and the member list is the clearest statement of the curriculum.

There is code/wasm-builder, which is the piece that compiles the examples for the browser. Then the beginner tutorials under code/beginner, the intermediate tutorials under code/intermediate, the compute tutorials at code/compute, and the `code/showcase` applications. The run-wasm directory and the demo_server directory are also workspace members, because the examples need a server to talk to.

Three crates under `code/showcase` are excluded from the workspace: the imgui-demo, pong and mouse-picking examples. That exclusion is worth a moment, because it tells you those three need something the rest do not, most likely a native window and a display, so they are built separately rather than as part of the workspace.

The remaining members are the compute tutorials, the wasm builder and the server, and the three tutorial directories. The progression from beginner to intermediate to compute to the larger applications is a real curriculum rather than a folder of unrelated examples, and the compute track is the one that goes past rendering into general purpose GPU work, which is where wgpu starts to look like a compute library rather than a graphics one.

The Examples Run in the Browser as WebAssembly

The documentation site is not a set of code blocks on a page. The build scripts show that the examples are compiled to WebAssembly and served alongside the documentation.

The package.json dev and build scripts both run the shell script that builds the WebAssembly before invoking the documentation builder, and there are just-build and just-dev variants that skip the WebAssembly step, which is the fast path when you are only editing prose. The build-wasm.sh script at the repository root is the entry point, and there is a wasm-targets.json file that describes the targets to build.

There is a run-wasm directory in the workspace and a demo_server directory, so the browser build of the examples is a Rust program that serves something, which means the same code that runs natively can run in a browser tab next to the explanation of it.

That is the design decision that makes this a guide rather than a reference. The README points at the Chinese translation and describes it as adding chapters on integrating with apps and on debugging, which suggests the same approach extended.

The WebAssembly toolchain is configured in the package.json with the Vite plugins for WebAssembly and for top level await, which is the flag you need when a module has to await at the top level before the page can use it.

The Documentation Site Is Vuepress

The docs are built with Vuepress, and the package.json shows the version and the pieces.

The package manager is yarn at 4.9.2, and the Vuepress stack is the release candidate line, with vuepress at 2.0.0-rc.26, the theme default at 2.0.0-rc.123 and the bundler at 2.0.0-rc.26. The styling runs through sass-embedded, and the Vue side is handled by the Vite plugin for Vue.

The build scripts pass NODE_OPTIONS=--openssl-legacy-provider to the Vuepress invocation, which is a workaround for the OpenSSL 3 change that broke older webpack style hashing in Node, and it is applied to every script including the just-build and just-dev ones, so it is a property of the toolchain rather than of one command.

There is a .yarnrc.yml at the root, which is where the yarn 4 settings live, and an index.template.html plus a res/ directory for the static resources the site needs.

The result is a documentation site that can host interactive WebAssembly examples, which is the reason for the Vuepress and Vite choice rather than a static site generator.

The Dependency List Is the Technology Choice

The workspace dependency section is short and reads like a description of what the tutorials are about:

[workspace.dependencies]
wgpu = "30.0"
glam = { version = "0.30.9", features = ["bytemuck", "serde"] }
bytemuck = { version = "1.13.1", features = ["derive"] }
winit = { version = "0.30", features = ["android-native-activity"] }

glam is the vector and matrix maths library, with the bytemuck and serde features enabled, and bytemuck itself with the derive feature is what lets a plain Rust struct be passed to the GPU without a copy. Those two are the foundation of how a wgpu program moves data to the device.

winit is the windowing library, and the android-native-activity feature is what lets the examples run on Android. env_logger and log handle the logging, pollster is the block_on wrapper for the async device calls, and the image crate handles textures. tobj is the OBJ loader, used by the examples that load a model, with the async feature enabled, and ab_glyph renders text, which is how the examples draw labels.

The remaining entries, flume for channels, web-time so the examples can run in a browser and on the web, and serde and serde_json, are the glue that lets one set of examples target a native window and a browser tab at once.

A Project Written to Learn, and What That Means for a Reader

The README is unusually candid about the nature of the project, and that candour is the first thing to read.

The author says he is using this project to learn wgpu himself, so he might miss some important details or explain things badly, and that he is always open to constructive feedback. That is an unusual thing to state in a tutorial's introduction, and it is the kind of statement that tells a reader what kind of document to expect.

The contribution policy follows from it. Pull requests are accepted for fixing issues with the tutorial such as typos, incorrect information and other inconsistencies. But due to wgpu's rapidly changing API, no new pull requests for the `code/showcase` demos are accepted.

The reason is practical rather than territorial. A demo application is a substantial piece of code written against an API that is still moving, and maintaining contributed demos against a moving API is work the author does not have. Fixing a wrong sentence is cheap; keeping three contributed applications compiling is not.

There is a patron link for direct support, and the README lists the patrons by name, and there is a Chinese translation maintained separately, described as adding chapters on integration with apps and on debugging.

Editorial conclusion

learn-wgpu fits a Rust developer who wants to learn wgpu from working code rather than from API documentation, and who will read a long tutorial end to end, since that is the form the project takes. It is a poor fit if you want a reference to look things up in, and it is a poor fit if your interest is in the applications under `code/showcase`, because the author is not accepting new pull requests for showcase demos while the wgpu API is moving. Before starting, note that the author is using the project to learn wgpu himself and says he might miss details, and that some of the documentation is subject to change because wgpu is still in development. The project is MIT licensed, the last push was on 2026-10-17, and it publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. sotrh/learn-wgpu on GitHub