Note: The final code for this example can be found on GitHub.
In this introductory example, we will develop a Browser-based application that uses the following call chain.
JavaScript
--> WebAssembly
--> Native "OS" function
In this case, we will invoke the a simple WASI module that does nothing more than writing hello world
to standard out.
The Wasm module calls the native "OS" function fd_write
that writes data to a particular file descriptor (hence fd
in the function name)
However, interaction with file descriptors such as "standard in" and "standard out" is not normally possible for a WebAssembly module, since this type of functionality belongs to the underlying "OS". Therefore, we must make use of the following two packages:
Package Name | Description |
| A set of JavaScript polyfills to bridge the gap between the black-box world of a WebAssembly module and functionality available in the host environment |
| Provide access to a sand-boxed filesystem with which |
The term "OS" used above is in quotes because in this particular case, the native function called by our WebAssembly module that writes to standard out, belongs to the JavaScript runtime, and not the actual underlying operating system.
This example will be bundled and served by Parcel and run in the browser.
Make sure Parcel has been installed and is available from the command line
$ npm install -g parcel
Before the installation of Parcel will work on a Mac, you must first install the Xcode Command Line Toolsâ
Change into some development directory
$ cd <some_development_directory>
Create and then change into a new project directory, then run npm init
$ mkdir wasmer-js-hello-world$ cd wasmer-js-hello-word$ npm init
After answering all the questions from npm init
, you will have a configured package.json
file.
For the purposes of testing, we need to install both the parcel-bundler
and parcel-plugin-static-files-copy
packages.
These packages allow parcel
to serve our Wasm files as static assets:
npm install --save-dev parcel-bundler parcel-plugin-static-files-copy
This command both installs the required packages and updates the devDependencies
section of your package.json
file.
Create a bare-bones index.html
file that contains nothing more than the request to load the JavaScript file index.js
:
<html><body><script src="./index.js"></script></body></html>
Create the file index.js
and add the following single line of code:
console.log('I am working')
Let's test that the basic file structure of our project is correct:
$ parcel index.htmlServer running at http://localhost:1234⨠Built in 1.15s.
Point your browser to http://localhost:1234
and you should see a blank page.
Open your browser's Developer Tools and look at the JavaScript console. Here, you should see "I am working"
, which means everything is working!
Now that the basic file structure of our project has been set up correctly, we must next declare the use of packages @wasmer/wasi
and @wasmer/wasmfs
.
To install these packages as runtime dependencies to our project, run the following command:
$ npm install --save @wasmer/wasi @wasmer/wasmfs
Create a new directory called static
$ mkdir static
Download the WebAssembly module helloworld.wasm
and store it in this directory
Now we need to change the contents of index.js
to implement the required functionality.
Seeing as this is demo code, it uses meaningful variable names and contains additional explanatory comments â features that are often sadly missing from production code...
Please take some time to read and understand these comments as they explain how the functionality has been constructed.
Also, please read the comment explaining the use of
@wasmer/wasm-transformer
; we will cover this very important detail in a later example.
import { WASI } from '@wasmer/wasi'import browserBindings from '@wasmer/wasi/lib/bindings/browser'import { WasmFs } from '@wasmer/wasmfs'âconst wasmFilePath = '/helloworld.wasm' // Path to our WASI moduleconst echoStr = 'Hello World!' // Text string to echoâ// Instantiate new WASI and WasmFs Instances// IMPORTANT:// Instantiating WasmFs is only needed when running in a browser.// When running on the server, NodeJS's native FS module is assigned by defaultconst wasmFs = new WasmFs()âlet wasi = new WASI({// Arguments passed to the Wasm Module// The first argument is usually the filepath to the executable WASI module// we want to run.args: [wasmFilePath, echoStr],â// Environment variables that are accesible to the WASI moduleenv: {},â// Bindings that are used by the WASI Instance (fs, path, etc...)bindings: {...browserBindings,fs: wasmFs.fs}})â// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -// Async function to run our WASI module/instanceconst startWasiTask =async pathToWasmFile => {// Fetch our Wasm Filelet response = await fetch(pathToWasmFile)let wasmBytes = new Uint8Array(await response.arrayBuffer())â// IMPORTANT:// Some WASI module interfaces use datatypes that cannot yet be transferred// between environments (for example, you can't yet send a JavaScript BigInt// to a WebAssembly i64). Therefore, the interface to such modules has to// be transformed using `@wasmer/wasm-transformer`, which we will cover in// a later exampleâ// Instantiate the WebAssembly filelet wasmModule = await WebAssembly.compile(wasmBytes);let instance = await WebAssembly.instantiate(wasmModule, {...wasi.getImports(wasmModule)});âwasi.start(instance) // Start the WASI instancelet stdout = await wasmFs.getStdOut() // Get the contents of stdoutdocument.write(`Standard Output: ${stdout}`) // Write stdout data to the DOM}â// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -// Everything starts herestartWasiTask(wasmFilePath)
As long as parcel
is still running, after saving index.js
, your browser should automatically refresh and you should see Standard Output: Hello World!
appear both on the browser screen and in the JavaScript console.
If you want to run the examples from the docs codebase directly, you can also do:
git clone https://github.com/wasmerio/docs.wasmer.io.gitcd docs.wasmer.io/integrations/js/wasi/browser/examples/hello-worldnpm run dev
Next, let's take a look at transforming WASI modules that require transformations.