# webassembly-examples: the code that backs MDN's WebAssembly documentation

> The mdn/webassembly-examples repository holds the runnable snippets behind MDN's WebAssembly guides, from JavaScript API examples to text format walkthroughs, with the .wasm binaries checked in next to the .wat sources. This looks at how the examples are organised, how you rebuild them, and what they are not.

**mdn/webassembly-examples** — Code examples that accompany the MDN WebAssembly documentation — see https://developer.mozilla.org/en-US/docs/WebAssembly. 

- Repository: https://github.com/mdn/webassembly-examples
- Stars: 1,214 · Forks: 267
- Language: WebAssembly
- License: CC0-1.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mdn-webassembly-examples

## Documentation scaffolding, not a library

webassembly-examples holds the code examples that accompany the MDN WebAssembly documentation, with the documentation itself at developer.mozilla.org. The repository description says exactly that, and the readme repeats it in the title line, which is a good sign about the project's self-awareness: it is not trying to be a framework, it is the runnable material behind a set of pages.

That framing decides how you should read it. Every file exists because a page on MDN links to it or shows it. There is no package to install, no API to call and no abstraction to learn. What you get is a set of small, complete, runnable programs that demonstrate one idea each, in a state that a browser can execute directly.

The primary language of the repository is WebAssembly, and the licence is CC0-1.0, the public domain dedication, which is the right choice for documentation samples. It means the code is not tied to the licence obligations of the documentation it accompanies, and it also means there is no warranty and no attribution expectation, which is convenient for a snippet someone will paste into a tutorial of their own.

The repository carries a `SECURITY.md` and a `CODE_OF_CONDUCT.md`, and a `template/` directory, which is the mechanism for adding a new example in the same shape as the existing ones.

## The directory names are the learning path

The top level of the repository is a map of the documentation itself, and reading the directory names tells you how the material is organised.

There is `js-api-examples/`, for the JavaScript-facing side of WebAssembly, the `WebAssembly` JavaScript API and how a module is instantiated and called. There is `js-builtin-examples/`, which covers what the runtime gives you for free rather than what you write yourself. There is `other-examples/`, for the cases that do not fit either of those, and `rust-js/`, which holds the Rust-to-JavaScript path where a Rust crate is compiled to WebAssembly and driven from the browser.

Then there are two directories that are really standalone pieces of material. `understanding-text-format/` is a walkthrough of the WebAssembly text format, the `.wat` syntax, and the repository even links a specific example file, `multi-memory.wat`, from inside it. `wasm-sobel/` is a self-contained project of its own, the Sobel edge detection filter, which is the classic way to show a non-trivial module doing real work on an image buffer.

The `template/` directory is the most telling piece for anyone extending the set. A template directory implies that the examples are not hand-assembled one at a time but generated from a common skeleton, so a new example follows the same layout, the same naming, and the same set of companion files as the existing ones.

## Every .wat has a .wasm twin that you have to rebuild

The mechanism that makes the examples work in a browser is the pairing of a text source with a compiled binary. The readme is explicit about the consequence: if you modify any `.wat` files for testing, you will need to generate a corresponding `.wasm` file, replacing the existing version in the folder.

That is a small rule with a large implication. The repository ships the compiled `.wasm` files, which is what makes the examples work when you serve them from a static server, since a browser cannot compile the text format. But it also means the binaries are checked-in artefacts that can drift from their sources, and a reader who edits a `.wat` and opens the example in a browser will see the old behaviour unless they remember to recompile.

The tool for that job is `wat2wasm`, which is part of WABT, the WebAssembly Binary Toolkit, and the readme links both the WABT repository and MDN's own guide on converting the text format into a binary file.

The two build artefacts therefore serve two different audiences. The `.wasm` file is for the reader who wants to run the example, and the `.wat` file is for the reader who wants to understand or change it. A contributor has to keep both in step, which is exactly the friction the readme warns about.

## Optional proposals need their flags spelled out

Not every example uses settled features of the specification, and the readme flags this before it shows any command. Some examples use features that are still considered optional, and they are listed in the supported proposals section of the WABT README, along with the flags used to invoke them.

The example given is the multi-memory example, where building the WASM for the `multi-memory.wat` file requires the `--enable-multi-memory` flag:

```sh
wat2wasm --enable-multi-memory multi-memory.wat
```

This is a detail that matters more than it looks. A reader who copies that example into their own project and compiles it with a plain `wat2wasm` invocation will get an error rather than a module, and the fix is not obvious unless you have read the WABT proposals table. The same applies to every other example that touches a proposal rather than the core specification.

The practical advice for anyone using these samples is to treat the flag list in the WABT README as part of the example, and to check which proposals the browsers you care about actually ship, because a feature that is in the specification and implemented by one browser is still a portability question for a documentation sample that is meant to work everywhere.

## Serving the examples needs a local server

The readme keeps the local testing instructions short and points at MDN's own guidance. The examples can be tested locally by running a local server to serve your directory of choice, with the link pointing at MDN's set_up_a_local_testing_server page and the anchor on the Python option.

That instruction is not incidental. A `.wasm` file has to be fetched over HTTP for the browser to instantiate it, and a browser will not let a page loaded from `file://` fetch the module the way it needs to. So the workflow for anyone working with these examples is the same: pick a directory, serve it, open the page.

The rest of the loop is the one from the previous section. Serve the directory, open the example, and if you have changed a `.wat` file, rebuild the `.wasm` with `wat2wasm` and the appropriate flag, and replace the binary in the folder. The readme is careful to point at both the WABT repository and the MDN page on the text format for setup and usage.

There is also a `rust-js/` directory, and that one is not a static file. It is the Rust path into the same story: a Rust crate compiled to WebAssembly, loaded and driven from JavaScript. A developer working through that directory needs a Rust toolchain and a wasm target, not just a static server, which is why it sits apart from the rest.

## Where webassembly-examples is the wrong tool

Three limits are worth stating plainly.

The first is that these are teaching artefacts, not maintained components. There are no GitHub releases, no package, no semantic versioning and no test runner. The examples are correct as of the day they were written, and a proposal can change underneath them. A team that copies a snippet into production inherits that fragility without the context the documentation provided, which is a good reason to read the page as well as the file.

The second is the checked-in binaries. Shipping a `.wasm` in your repository means shipping an artefact that a compiler produced, and the readme is honest that editing the `.wat` does not change what the browser runs until you rebuild. For a repository whose whole content is small self-contained programs, that is a reasonable trade, since there is no build system to run on the reader's machine. For anything larger, the pattern does not scale, and the right answer is to compile at build time in your own pipeline instead of copying a binary out of someone else's repository.

The third is coverage of optional features. The examples deliberately reach beyond the settled core, which is what makes them interesting, and which also means several of them will not run everywhere. That is a poor basis for a compatibility baseline and a good basis for learning.

On maintenance, the last push to the repository was on 2026-09-18, so the set is being kept current, and the structure with a template directory suggests the examples are still being added to rather than frozen. The licence is CC0-1.0, which places no obligations on reuse and, equally, offers no support commitment.

## Conclusion

webassembly-examples fits a developer learning the WebAssembly text format, a writer who needs a runnable snippet to link to, and a teacher who wants the same samples working locally. It does not fit a team looking for a WebAssembly toolchain, a build system, or a maintained library, since it is documentation scaffolding rather than a product. It is also the wrong source to copy code from without checking the proposal flags, because several examples rely on features that are still optional in the specification. Before you use a snippet in your own project, regenerate it with `wat2wasm` using the flag the WABT README lists, and check that the browsers you target actually implement the proposal.

## FAQ

### What is in the mdn/webassembly-examples repository?

The runnable code samples behind MDN's WebAssembly documentation, organised into directories such as js-api-examples/, js-builtin-examples/, other-examples/, rust-js/, understanding-text-format/ and wasm-sobel/, plus a template/ directory for adding new examples in the same shape.

### How do I rebuild a .wasm file after editing a .wat example?

Use `wat2wasm` from WABT. The readme notes that for most examples this can be done with the tool, and that some examples need the flag for the optional proposal they use, for example `wat2wasm --enable-multi-memory multi-memory.wat` for the multi-memory example.

### How do I test the webassembly-examples locally?

Run a local server to serve the directory you want, following the MDN guide on setting up a local testing server that the readme links, then open the example in your browser. A server is needed because the browser has to fetch the .wasm module over HTTP.

### Which WebAssembly proposals do these examples use?

Some of them use features that are still optional. The readme points to the supported proposals section of the WABT README, which lists the proposals along with the flags used to invoke them.

### What licence are the MDN WebAssembly examples under?

CC0-1.0, the public domain dedication, with the licence file at the repository root. The repository also carries a SECURITY.md and a CODE_OF_CONDUCT.md, and the last push was on 2026-09-18.

## Sources

- [Issues](https://github.com/mdn/webassembly-examples/issues)
- [License: CC0-1.0](https://github.com/mdn/webassembly-examples/blob/main/LICENSE)
- [mdn/webassembly-examples on GitHub](https://github.com/mdn/webassembly-examples)
- [README](https://github.com/mdn/webassembly-examples/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mdn-webassembly-examples