Loading and running WebAssembly code

To use WebAssembly in JavaScript, you first need to pull your module into memory before compilation/instantiation. This article provides a reference for the different mechanisms that can be used to fetch WebAssembly bytecode, as well as how to compile/instantiate then run it.

WebAssembly is not yet integrated with <script type='module'> or ES2015 import statements, thus there is not a path to have the browser fetch modules for you using imports.

The older WebAssembly.compile/WebAssembly.instantiate methods require you to create an ArrayBuffer containing your WebAssembly module binary after fetching the raw bytes, and then compile/instantiate it. This is analogous to new Function(string), except that we are substituting a string of characters (JavaScript source code) with an array buffer of bytes (WebAssembly source code).

The newer WebAssembly.compileStreaming/WebAssembly.instantiateStreaming methods are a lot more efficient — they perform their actions directly on the raw stream of bytes coming from the network, cutting out the need for the ArrayBuffer step.

So how do we get those bytes into an array buffer and compiled? The following sections explain.

Fetch is a convenient, modern API for fetching network resources.

The quickest, most efficient way to fetch a wasm module is using the newer WebAssembly.instantiateStreaming() method, which can take a fetch() call as its first argument, and will handle fetching, compiling, and instantiating the module in one step, accessing the raw byte code as it streams from the server:

WebAssembly.instantiateStreaming(fetch('simple.wasm'), importObject)
.then(results => {
  // Do something with the results!
});

If we used the older WebAssembly.instantiate() method, which doesn't work on the direct stream, we'd need an extra step of converting the fetched byte code to an ArrayBuffer, like so:

fetch('module.wasm').then(response =>
  response.arrayBuffer()
).then(bytes =>
  WebAssembly.instantiate(bytes, importObject)
).then(results => {
  // Do something with the results!
});

The WebAssembly.instantiate() function has two overload forms — the one shown above takes the byte code to compile as an argument and returns a Promise that resolves to an object containing both the compiled module object and an instantiated instance of it. The object looks like this:

{
  module : Module // The newly compiled WebAssembly.Module object,
  instance : Instance // A new WebAssembly.Instance of the module object
}

Once you've got your WebAssembly instance available in your JavaScript, you can then start using features of it that have been exported via the WebAssembly.Instance.exports property. Your code might look something like this:

WebAssembly.instantiateStreaming(fetch('myModule.wasm'), importObject)
.then(obj => {
  // Call an exported function:
  obj.instance.exports.exported_func();

  // or access the buffer contents of an exported memory:
  var i32 = new Uint32Array(obj.instance.exports.memory.buffer);

  // or access the elements of an exported table:
  var table = obj.instance.exports.table;
  console.log(table.get(0)());
})

XMLHttpRequest is somewhat older than Fetch, but can still be happily used to get a typed array. Again, assuming our module is called simple.wasm:

1. Create a new XMLHttpRequest() instance, and use its open() method to open a request, setting the request method to GET, and declaring the path to the file we want to fetch.
2. The key part of this is to set the response type to 'arraybuffer' using the responseType property.
3. Next, send the request using XMLHttpRequest.send().
4. We then use the load event handler to invoke a function when the response has finished downloading — in this function we get the array buffer from the response property, and then feed that into our WebAssembly.instantiate() method as we did with Fetch.

The final code looks like this:

request = new XMLHttpRequest();
request.open('GET', 'simple.wasm');
request.responseType = 'arraybuffer';
request.send();

request.onload = function() {
  var bytes = request.response;
  WebAssembly.instantiate(bytes, importObject).then(results => {
    results.instance.exports.exported_func();
  });
};