{"canonical_url":"https://engineer.company/glossary/webassembly/","content_markdown":"# WebAssembly\n\n## What it is\n\nWebAssembly, usually shortened to Wasm, is a binary format for executable code.\nIts core specification calls it “a safe, portable, low-level code format\ndesigned for efficient execution and compact representation”, and describes it\nas a virtual instruction set: the instructions of an imagined processor, which a\nbrowser or another host first checks and then translates into machine code for\nthe real one. The short form is a contraction, not an acronym, which is why the\nspecification writes Wasm and not WASM.\n\nA `.wasm` file is usually the output of a compiler for some other language. The\nmain goal, in the specification's own account, is fast applications on the Web,\nbut the format makes no assumptions about the Web, so it can also run as a\nstand-alone virtual machine or inside other programs. The standard is layered to\nmatch: the core specification defines the instructions, the formats, validation\nand execution, and no particular environment. Separate documents define the\nJavaScript API that compiles, links and calls modules, and the Web API that\nloads them over the network.\n\nThe first version became a W3C Recommendation on 5 December 2019. Version 2.0,\nessentially finished three years before its successor, added instructions that\nwork on vectors, bulk operations on memory, functions with more than one return\nvalue, and a simple first form of reference types. On 17 September 2025 the\nproject announced version 3.0 as the standard now in force, and said it was\nalready shipping in most major browsers. The same announcement names Java,\nOCaml, Scala, Kotlin, Scheme and Dart among the languages that now target Wasm\nthrough its garbage collector.\n\nThe vocabulary is small. The unit of code is a module: it holds functions,\ntables, memories and global variables, imports what it needs, each import\nnamed by a module name and an item name, and exports what it offers under\nnames of its own. There are four number types, 32-bit and 64-bit integers and\nfloating-point numbers, written `i32`, `i64`, `f32` and `f64`, plus a single\n128-bit vector type and opaque references. Integers carry no sign of their\nown; each operation reads them as signed or unsigned, and a 32-bit integer\nalso serves as a Boolean. Memory addresses use `i32` or, for a 64-bit memory,\n`i64`. Instructions take their operands from an implicit stack and leave their\nresults on it, and control flow is structured: blocks, loops and conditionals\nnest, and a branch can only target one of them.\n\nByte-addressed data lives in a linear memory, one continuous, writable array\nof bytes that starts at a declared size and can grow while the program runs. A\nload or a store outside its current size does not reach anything else. It\ntraps, which stops execution at once, and a trap cannot be handled inside\nWasm, only reported to the host around it. The example below uses the text\nformat the specification defines for people to read.\n\n## Why it matters\n\nSpeed is the first reason. The design goals ask for performance close to native\ncode and a format that a single fast pass can decode, validate and compile,\nwhether the compiler runs just in time or ahead of time. The binary is meant to\nbe more compact than both text and native machine code, and it is streamable:\nwork can begin before the last byte has arrived. The binary format even keeps\neach function's type declaration in a different section from its body, so that\nthe bodies can be compiled in parallel and while they stream in. A team that\nalready owns a well-tested library in another language can compile it for the\nbrowser instead of rewriting it in JavaScript.\n\nPortability is the second. The same module runs on any modern processor, desktop\nor mobile, and in any host that embeds an engine: a browser, a stand-alone\nruntime or another program. The specification favours no particular language,\nprogramming model or object model, so the format is a common target rather than\none language's private runtime.\n\nContainment is the third. A module has no ambient access to the computer it runs\non. Files, the network, the page and the clock are out of reach unless the host\nhands it a function for them as an import, so the host decides exactly what the\ncode may touch. On the Web, the Web API notes that Wasm can run wherever\nJavaScript can and has essentially the same threat model, and cannot expose more\nthan JavaScript already could. Version 3.0 widened what fits inside that\nboundary: memories that can be addressed with 64 bits, limited on the web to 16\ngigabytes, several memories in one module, a garbage collector for languages\nthat expect one, and exceptions that no longer have to escape to the host, which\nthe announcement calls neither portable nor efficient.\n\n## What it looks like in practice\n\nHere is a module in the text format, with a single exported function that adds\ntwo 32-bit integers:\n\n```wat\n(module\n  (func (export \"add\") (param i32 i32) (result i32)\n    local.get 0\n    local.get 1\n    i32.add))\n```\n\nThe function's type says it takes two `i32` values and returns one. The body is\nthree instructions on the stack: `local.get 0` pushes the first parameter,\n`local.get 1` pushes the second, and `i32.add` pops both and pushes their sum,\nwhich is left on the stack as the result. `(export \"add\")` gives the function\nthe name the outside world sees. Converted to the binary format, the file starts\nwith the four bytes `0x00 0x61 0x73 0x6D`, a zero followed by the letters asm,\nand then the binary format's version, which is still 1.\n\nIn a browser, the JavaScript API loads it:\n\n```js\nconst url = \"/add.wasm\";\nconst { instance } = await WebAssembly.instantiateStreaming(fetch(url));\ninstance.exports.add(2, 3); // 5\ninstance.exports.add(2147483647, 1); // -2147483648\n```\n\n`instantiateStreaming` compiles the module while the response is still arriving\nand resolves to the compiled module and an instance of it. The instance's\nexports are ordinary JavaScript functions. The second call shows what the types\nmean: integer addition in Wasm wraps around modulo 2 to the power of 32, and the\nJavaScript API reads an `i32` result as signed, so one more than the largest\npositive value comes back as the most negative one. Nothing is thrown. A trap\nwould be, though: if a function reads outside its memory, the call ends in a\n`WebAssembly.RuntimeError`.\n\nA module that needs something from its host says so. With\n`(import \"env\" \"log\" (func (param i32)))` in the module, instantiation needs a\nsecond argument, `{ env: { log: console.log } }`, and the module can call\n`log` like any of its own functions. Leave the second argument out and\ninstantiation fails with a `TypeError`; pass an `env` object without a\ncallable `log` and it fails with a `WebAssembly.LinkError`, in both cases\nbefore any of the module's code has run. Imports and exports are the whole\nboundary, with declared types that include numbers and references; an address\nin the module's memory is an `i32`, or an `i64` for a 64-bit memory.\n\n[A portfolio entry on building a native macOS client in Swift 6](/portfolio/built-a-native-macos-client-in-swift-6/)\ndescribes the other way of reusing code from another language. In that work,\ncarried out in August 2026, a Rust core was linked into a Swift application as a\nstatic archive and reached through its C interface, which the entry treats as\nthe contract. A thin wrapper owns every pointer and every string that crosses\nthe boundary, and everything the interface returns has an ownership rule, where\na mistake means a leak or a crash with no compiler warning. No Wasm is involved\nthere, which is what makes the comparison useful: the same problem of a narrow\nboundary between two languages, solved with native linking instead of an import\nlist and a sandboxed memory.\n\n## Where it goes wrong\n\n**The promise rejects before anything compiles.** A missing `Content-Type`, or\nany value other than `application/wasm` with case ignored, fails with a\n`TypeError`, and the specification notes that extra parameters are not allowed,\nnot even an empty `application/wasm;`. A status that is not ok fails the same\nway, and so does a response from another origin that CORS does not make\nsame-origin. Fix the server's media type and headers. `WebAssembly.instantiate`\non bytes you have fetched yourself skips the media type check but loses the\nstreaming compilation.\n\n**A view of memory goes dead.** JavaScript sees a module's memory through\n`memory.buffer` and the arrays built on it. For unshared memory, this buffer is\nfixed-length by default. When the memory grows, the JavaScript API detaches\nthat fixed-length buffer and replaces it with a new one, so arrays built on the\nold buffer are cut off from the memory. This happens after `memory.grow()`\ncalled from JavaScript and also after a `memory.grow` instruction inside the\nmodule, during a call that looks harmless from outside. Create views from\n`memory.buffer` again after any call that may grow the memory, rather than\nkeeping one for the lifetime of the page.\n\n**Expecting Wasm to reach the page by itself.** A module has no ambient access\nto anything, so every effect on the page, the network or storage goes through a\nfunction JavaScript passes in as an import. Types bite at the same boundary: an\n`i64` crosses as a `BigInt`, not a number, and a function with a `v128`\nparameter or result throws a `TypeError` each time JavaScript calls it. Design\nthe import and export list as an interface, with plain numbers on it, and keep\nvectors on the Wasm side.\n\n**Taking the sandbox for a safe program.** The sandbox protects the host from\nthe module. It does not protect the module from itself. The specification states\nthat it cannot stop an unsafe language compiled to Wasm from corrupting its own\nmemory layout inside linear memory: a buffer overflow in compiled code\noverwrites the module's own data, and only an access past the end of the whole\nmemory traps. Keep the source language's own checks and tests, and treat data\nthe module receives from outside as untrusted input.\n\n**Shipping the binary without protecting it.** The registration of\n`application/wasm` says the format includes no integrity or privacy protection,\nand that where such protection is needed it must come from outside, through\nHTTPS for example. As with JavaScript, some ways of loading and running it are\nlimited by Content Security Policy or by the same-origin policy. And because\nWasm becomes machine code on real hardware, the core specification warns that it\nis potentially open to side-channel attacks at the hardware level. Serve modules\nover HTTPS, and guard who may change a module as closely as who may change a\nscript.\n\n## Further reading\n\n- [WebAssembly Specification](https://webassembly.github.io/spec/core/)\n  — the core specification for version 3.0: structure, validation, execution and\n  the binary and text formats.\n- [Introduction](https://webassembly.github.io/spec/core/intro/introduction.html)\n  — the definition, the design goals, the scope of each document and the\n  security considerations.\n- [WebAssembly JavaScript Interface](https://webassembly.github.io/spec/js-api/)\n  — compiling and instantiating from JavaScript, how values cross, `Memory.grow`\n  and the three error classes.\n- [WebAssembly Web API](https://webassembly.github.io/spec/web-api/)\n  — `instantiateStreaming`, the checks on the response and the\n  `application/wasm` registration.\n- [Wasm 3.0 Completed](https://webassembly.org/news/2025-09-17-wasm-3.0/)\n  — the announcement of 17 September 2025 and what version 3.0 adds.\n- [WebAssembly Core Specification 1.0](https://www.w3.org/TR/wasm-core-1/)\n  — the W3C Recommendation of 5 December 2019.\n\n\u003chttps://engineer.company/glossary/webassembly/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"What Wasm is and how a module works: the stack, linear memory, imports and exports, loading it from JavaScript, and where it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/webassembly/index.gmi","gopher":"https://engineer.company/glossary/webassembly/gophermap","html":"https://engineer.company/glossary/webassembly/","json":"https://engineer.company/glossary/webassembly/index.json","markdown":"https://engineer.company/glossary/webassembly/index.md","pdf":"https://engineer.company/glossary/webassembly/index.pdf"},"kind":"page","language":"en","title":"What is WebAssembly?","url":"https://engineer.company/glossary/webassembly/","version":1}