WebAssembly.instantiate()
The WebAssembly.instantiate()
function allows you to
compile and instantiate WebAssembly code. This function has two overloads:
-
The primary overload takes the WebAssembly binary code, in the form of a typed array or
ArrayBuffer
, and performs both compilation and instantiation in one step. The returnedPromise
resolves to both a compiledWebAssembly.Module
and its firstWebAssembly.Instance
. -
The secondary overload takes an already-compiled
WebAssembly.Module
and returns aPromise
that resolves to anInstance
of thatModule
. This overload is useful if theModule
has already been compiled.
Warning: This method is not the most efficient way of fetching and
instantiating Wasm modules. If at all possible, you should use the newer
WebAssembly.instantiateStreaming()
method instead, which fetches,
compiles, and instantiates a module all in one step, directly from the raw bytecode,
so doesn't require conversion to an ArrayBuffer
.
Syntax
Primary overload — taking Wasm binary code
js
WebAssembly.instantiate(bufferSource, importObject);
Parameters
bufferSource
-
A typed array or
ArrayBuffer
containing the binary code of the Wasm module you want to compile, or aWebAssembly.Module
. importObject
Optional-
An object containing the values to be imported into the newly-created
Instance
, such as functions orWebAssembly.Memory
objects. There must be one matching property for each declared import of the compiled module or else aWebAssembly.LinkError
is thrown.
Return value
A Promise
that resolves to a ResultObject
which contains two
fields:
module
: AWebAssembly.Module
object representing the compiled WebAssembly module. ThisModule
can be instantiated again, shared viapostMessage()
, or cached.instance
: AWebAssembly.Instance
object that contains all the Exported WebAssembly functions.
Exceptions
-
If either of the parameters are not of the correct type or structure,
the promise rejects with a
TypeError
. -
If the operation fails, the promise rejects with a
WebAssembly.CompileError
,WebAssembly.LinkError
, orWebAssembly.RuntimeError
, depending on the cause of the failure.
Secondary overload — taking a module object instance
js
WebAssembly.instantiate(module, importObject);
Parameters
module
-
The
WebAssembly.Module
object to be instantiated. importObject
Optional-
An object containing the values to be imported into the newly-created
Instance
, such as functions orWebAssembly.Memory
objects. There must be one matching property for each declared import ofmodule
or else aWebAssembly.LinkError
is thrown.
Return value
A Promise
that resolves to an WebAssembly.Instance
object.
Exceptions
-
If either of the parameters are not of the correct type or structure, a
TypeError
is thrown. -
If the operation fails, the promise rejects with a
WebAssembly.CompileError
,WebAssembly.LinkError
, orWebAssembly.RuntimeError
, depending on the cause of the failure.
Examples
Note: You'll probably want to use WebAssembly.instantiateStreaming()
in most cases, as it is more efficient than instantiate()
.
First overload example
After fetching some WebAssembly bytecode using fetch, we compile and instantiate the
module using the WebAssembly.instantiate()
function, importing a
JavaScript function into the WebAssembly Module in the process. We then call an Exported WebAssembly function
that is exported by the Instance
.
js
const importObject = {
imports: {
imported_func(arg) {
console.log(arg);
},
},
};
fetch("simple.wasm")
.then((response) => response.arrayBuffer())
.then((bytes) => WebAssembly.instantiate(bytes, importObject))
.then((result) => result.instance.exports.exported_func());
Note: You can also find this example at index.html on GitHub (view it live also).
Second overload example
The following example (see our index-compile.html
demo on GitHub, and view it live also)
compiles the loaded simple.wasm byte code using the
WebAssembly.compileStreaming()
method and then sends it to a worker using
postMessage()
.
js
const worker = new Worker("wasm_worker.js");
WebAssembly.compileStreaming(fetch("simple.wasm")).then((mod) =>
worker.postMessage(mod)
);
In the worker (see
wasm_worker.js
)
we define an import object for the module to use, then set up an event handler to
receive the module from the main thread. When the module is received, we create an
instance from it using the WebAssembly.instantiate()
method and invoke an
exported function from inside it.
js
const importObject = {
imports: {
imported_func(arg) {
console.log(arg);
},
},
};
onmessage = (e) => {
console.log("module received from main thread");
const mod = e.data;
WebAssembly.instantiate(mod, importObject).then((instance) => {
instance.exports.exported_func();
});
};
Specifications
Specification |
---|
WebAssembly JavaScript Interface # dom-webassembly-instantiate |
Browser compatibility
BCD tables only load in the browser