webgpu-headers is one C header for a JavaScript graphics API

What the header is, and what it is not

This repository contains the stable C header webgpu.h, described as a C API equivalent of the WebGPU API for JavaScript. The distinction is that WebGPU itself is a JavaScript API made for the web, and this header is the same API expressed in C, so that native programs can use it.

The README's justification is worth reading because it explains the whole project in two paragraphs. WebGPU is described as a good tradeoff of ergonomic, efficient and portable graphics API, and almost all of its concepts are not specific to the web platform. The headers replicate those concepts exactly, while adding capabilities to interact with native concepts such as windowing.

So this is not a new graphics API and not a subset of one. It is the same object model, with the places where the web had no concept filled in with the native equivalent.

The scope of the documentation is stated as well. The header, its documentation and the attached documentation articles describe the native specifics of the C API, and for everything else you are referred to the WebGPU specification. Together, the header and the WebGPU specification form a rough specification for webgpu.h. The word rough is doing honest work there, since the arrangement is a shared contract between independent projects rather than a ratified standard.

Multiple implementations strive to implement that specification compatibly, in addition to their own extensions, which are not specified here. For those extensions you use your implementation's extended headers.

Three implementations, one contract

The README lists the implementations of the header, and they cover the three ways WebGPU is actually used.

Dawn is the C++ WebGPU implementation used in Chromium. Emdawnwebgpu is for Emscripten, and it translates webgpu.h calls into JavaScript WebGPU calls when compiling to WebAssembly, which is how a C program compiled to WebAssembly can drive the browser's own GPU stack. wgpu-native is the C binding to wgpu, the Rust WebGPU implementation used in Firefox, and it is the route for a native C program that wants to sit on the Rust implementation.

That third entry carries an explicit caveat in bold in the README: wgpu-native does not yet implement the stable version of this header, and contributions are needed. That single line is the most important practical fact in the document for a user choosing an implementation, and it cuts both ways. It means the Firefox side is not yet a drop-in match for the stable header, so a program written against webgpu.h may not compile or behave identically there. It also means the header is still moving, and a project that pins to it should expect to track changes.

For the audience, this is a project for people writing native code that has to interoperate with WebGPU, or writing language bindings and tooling against it, and for the implementers themselves, who use it as the shared reference between their code and everyone else's.

webgpu.yml is the file that actually matters

The machine-readable source of truth is webgpu.yml, and webgpu.json holds the same contents in a different format. These two files are the main source of truth for the C API and its documentation, and they are what the official webgpu.h header and the official documentation are generated from.

The README goes further and says the data may be used by any other third party to design tools and wrappers around WebGPU-Native, especially bindings into other languages. That is the important sentence for adoption. A YAML description of an API is a far better input for a binding generator than a C header is, because the header has already thrown away the type relationships and the documentation comments that a generator needs.

There is also a specific invitation attached. If you are developing bindings of webgpu.h into another language and find that any additional high-level or semantic information would be useful in webgpu.yml, you are asked to contribute it. The implication is that the YAML carries more than the C API mechanically requires, and that the project wants that extra information recorded for the benefit of the next binding author.

The practical advice for a binding author is therefore to read the YAML rather than the header, and to consider whether the semantics you need are recorded there, and to propose an addition if they are not.

The generator, the schema and the compile check

The tooling is a Go program, and the repository layout says so. The gen directory and the go.* files are the source of the generator that the Makefile calls, and the go.mod shows it needs Go 1.21 with two direct dependencies, a YAML library and a JSON Schema validator. The fix directory holds the autoformatter for the YAML.

The Makefile's gen target is the core of it, and it is worth reading closely because it does more than emit a header:

gen: schema.json webgpu.yml tests/extensions/extension.yml
	go run ./gen -schema schema.json \
		-yaml webgpu.yml \
		-out-json webgpu.json \
		-out-header webgpu.h \
		-yaml tests/extensions/extension.yml \
		-out-json tests/extensions/extension.json \
		-out-header tests/extensions/webgpu_extension.h

The schema is validated as part of generation, and the same command produces the extension test files. After generating, the Makefile derives a compile test for every INIT macro defined in the header, using a one-line Perl expression that rewrites each macro definition into an assignment, and then asserts that the resulting file has at least 89 lines. That assertion is a guard on the generator itself, in case a change to the generator silently stops matching the macros.

The other checks are equally practical. The tests/compile directory is used to check that the generated C header is indeed valid C or C++ code, so the header is compiled rather than merely reviewed. The .github/workflows directory defines the automated processes that run on new commits and pull requests to check that changes in webgpu.yml and webgpu.h are consistent. And the doc target runs Doxygen and then greps the generated HTML to verify that no backticks or the :: scope operator made it into the documentation, which is a check on the markdown-to-HTML conversion rather than on the API.

The contribution rule is three files in step

The contributing section states the rule in bold, and it is the single most important thing for a contributor to get right.

When submitting a change, one must modify webgpu.yml, webgpu.json and webgpu.h files in a consistent way. The order is prescribed: first edit webgpu.yml, the source of truth, then run make gen to update webgpu.json and webgpu.h, and finally commit all changes together.

The consistency check is automated. The gen-check target regenerates the files, including the autoformat step, and then uses git diff to fail the build if anything changed, printing an error that asks the contributor to run make gen fix or apply the changes manually. A pull request that edits the YAML without regenerating therefore fails on its own consistency, with a diff attached.

That is a good design for a repository whose central artefact is generated. It removes the possibility of a hand-edited header drifting from the source, and it removes the question of what to do when a contributor thinks the generated output is wrong. The cost is that a change to the YAML is not a one-file change, and the reviewer has to read the generated diff as well as the source diff.

The doc target is part of the default make invocation, since the all target depends on gen, fix and doc, so a local build of the repository produces the header, the formatted YAML and the documentation in one pass.

Licence, releases and what the repository contains

The licence is BSD-3-Clause, with the LICENSE file at the root of the repository, which is a permissive licence suitable for a header that other projects vendor into their own source trees.

There are no GitHub releases, and the project is not archived, with the last push on 2026-09-29. For a header project that is the expected arrangement, since the artefact is a single file in the repository rather than a package that needs versioned releases, but it does mean consumers track a commit rather than a tag.

The top-level entries show the whole shape of the project. There is webgpu.h, the one and only header file that defines the WebGPU C API, which is the only thing that needs to be integrated into a C project that links against a WebGPU implementation, with the caveat that you should use your implementation's headers if you need extensions or if the implementation does not match this header exactly. There are the two source data files, the schema.json that formally specifies the structure of webgpu.yml, the generator sources in gen with the go.mod and go.sum, the fix tooling, the tests directory, the doc directory with a Doxyfile for the documentation build, and the .github workflows.

The documentation is published at webgpu-native.github.io/webgpu-headers, and the README links it directly. For a header whose only job is to be read by other people's compilers and by binding generators, having the documentation and the machine readable description in the same place is most of the value.

Editorial conclusion

webgpu-headers fits a team writing a native binding, a wrapper generator or a tool that has to speak to more than one WebGPU implementation, since the point of the header is that Dawn and wgpu-native can be swapped underneath without changing the calling code. It is the wrong choice if you are writing JavaScript, where the WebGPU specification already is the API, and it is the wrong choice if you need implementation specific extensions, which live in each implementation's own extended headers. Before adopting it, read the header and the attached documentation for the native specifics, check whether your chosen implementation actually matches the stable version of the header, and follow the contribution workflow exactly, since a change to the YAML without a regenerated header will fail the repository's own consistency check.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. Project website
4. README
5. webgpu-native/webgpu-headers on GitHub