Hello World

Note: The final code for this example can be found on Github: hello-world.
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.
Under the Hood
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
@wasmer/wasi
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
@wasmer/wasmfs
Provide access to a sand-boxed filesystem with which @wasmer/wasi can interact
Reminder
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.
Setup Instructions
Prerequisites
Make sure Parcel has been installed and is available from the command line
1
$ npm install -g parcel
Copied!
Mac users
Before the installation of Parcel will work on a Mac, you must first install the Xcode Command Line Tools​
Step-By-Step Guide
1.
Change into some development directory
1
 $ cd <some_development_directory>
Copied!
2.
Create and then change into a new project directory, then run npm init
1
 $ mkdir wasmer-js-hello-world
2
 $ cd wasmer-js-hello-word
3
 $ npm init
Copied!
After answering all the questions from npm init, you will have a configured package.json file.
3.
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:
1
 npm install --save-dev parcel-bundler parcel-plugin-static-files-copy
Copied!
This command both installs the required packages and updates the devDependencies section of your package.json file.
4.
Create a bare-bones index.html file that contains nothing more than the request to load the JavaScript file index.js:
1
 <html>
2
 <body>
3
   <script src="./index.js"></script>
4
 </body>
5
 </html>
Copied!
5.
Create the file index.js and add the following single line of code:
1
 console.log('I am working')
Copied!
6.
Let's test that the basic file structure of our project is correct:
1
 $ parcel index.html
2
 Server running at http://localhost:1234 
3
 ✨  Built in 1.15s.
Copied!
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!
7.
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:
1
$ npm install --save @wasmer/wasi @wasmer/wasmfs
Copied!
8.
Create a new directory called static
1
 $ mkdir static
Copied!
9.
Download the WebAssembly module helloworld.wasm and store it in this directory
10.
Now we need to change the contents of index.js to implement the required functionality.
Code Sample
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.
1
import { WASI } from '@wasmer/wasi'
2
import browserBindings from '@wasmer/wasi/lib/bindings/browser'
3
import { WasmFs } from '@wasmer/wasmfs'
4
​
5
const wasmFilePath = '/helloworld.wasm'  // Path to our WASI module
6
const echoStr      = 'Hello World!'    // Text string to echo
7
​
8
// Instantiate new WASI and WasmFs Instances
9
// IMPORTANT:
10
// Instantiating WasmFs is only needed when running in a browser.
11
// When running on the server, NodeJS's native FS module is assigned by default
12
const wasmFs = new WasmFs()
13
​
14
let wasi = new WASI({
15
  // Arguments passed to the Wasm Module
16
  // The first argument is usually the filepath to the executable WASI module
17
  // we want to run.
18
  args: [wasmFilePath, echoStr],
19
​
20
  // Environment variables that are accesible to the WASI module
21
  env: {},
22
​
23
  // Bindings that are used by the WASI Instance (fs, path, etc...)
24
  bindings: {
25
    ...browserBindings,
26
    fs: wasmFs.fs
27
  }
28
})
29
​
30
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
31
// Async function to run our WASI module/instance
32
const startWasiTask =
33
  async pathToWasmFile => {
34
    // Fetch our Wasm File
35
    let response  = await fetch(pathToWasmFile)
36
    let wasmBytes = new Uint8Array(await response.arrayBuffer())
37
​
38
    // IMPORTANT:
39
    // Some WASI module interfaces use datatypes that cannot yet be transferred
40
    // between environments (for example, you can't yet send a JavaScript BigInt
41
    // to a WebAssembly i64).  Therefore, the interface to such modules has to
42
    // be transformed using `@wasmer/wasm-transformer`, which we will cover in
43
    // a later example
44
​
45
    // Instantiate the WebAssembly file
46
    let wasmModule = await WebAssembly.compile(wasmBytes);
47
    let instance = await WebAssembly.instantiate(wasmModule, {
48
       ...wasi.getImports(wasmModule)
49
    });
50
​
51
    wasi.start(instance)                      // Start the WASI instance
52
    let stdout = await wasmFs.getStdOut()     // Get the contents of stdout
53
    document.write(`Standard Output: ${stdout}`) // Write stdout data to the DOM
54
  }
55
​
56
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
57
// Everything starts here
58
startWasiTask(wasmFilePath)
Copied!
11.
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:
1
git clone https://github.com/wasmerio/docs.wasmer.io.git
2
cd docs.wasmer.io/integrations/js/wasi/browser/examples/hello-world
3
npm run dev
Copied!
Next, let's take a look at transforming WASI modules that require transformations.
Examples
Transforming Modules
Last modified 8mo ago
Copy link
Contents
Setup Instructions
Prerequisites
Step-By-Step Guide