The Wasmer JavaScript SDK

Javascript library for running Wasmer packages at ease, including WASI and WASIX modules.

Getting Started

Install from NPM

For instaling @wasmer/sdk, run this command in your shell:

npm install --save @wasmer/sdk

You can now run WASI packages from the Wasmer registry:

import { init, Wasmer } from "@wasmer/sdk";

await init();

const pkg = await Wasmer.fromRegistry("python/python");
const instance = await pkg.entrypoint.run({
    args: ["-c", "print('Hello, World!')"],
});

const { code, stdout } = await instance.wait();
console.log(`Python exited with <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>c</mi><mi>o</mi><mi>d</mi><mi>e</mi></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{code}: </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord"><span class="mord mathnormal">co</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{stdout}`);

Use with a <script> tag (without bundler)

It is possible to avoid needing to use a bundler by importing @wasmer/sdk as a UMD module.

By adding the following <script> tag to your index.html file, the library will be available as the WasmerSDK global variable.

<script src="https://unpkg.com/@wasmer/sdk@latest"></script>
<script>
    const { init, Wasmer } = WasmerSDK;

      async function runPython() {
          await init();

          const packageName = "python/python";
          const pkg = await Wasmer.fromRegistry(packageName);
          const instance = await pkg.entrypoint.run({
              args: ["-c", "print('Hello, World!')"],
          });

          const { code, stdout } = await instance.wait();

          console.log(`Python exited with <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>c</mi><mi>o</mi><mi>d</mi><mi>e</mi></mrow><mo>:</mo></mrow><annotation encoding="application/x-tex">{code}: </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord"><span class="mord mathnormal">co</span><span class="mord mathnormal">d</span><span class="mord mathnormal">e</span></span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">:</span></span></span></span>{stdout}`);
      }

      runPython();
</script>

Alternatively, the package can be imported directly from the CDN by turning the script into a module.

<script defer type="module">
    import { init, Wasmer } from "https://unpkg.com/@wasmer/sdk@latest?module";

    async function runPython() {
        await init();

        ...
    }

    runPython();
</script>

Using a custom Wasm file

By default, WasmerSDK.init will load the Wasmer SDK WebAssembly file from unpkg.com. If you want to customize this behavior you can pass a custom url to the init, so the the wasm file of the Wasmer SDK can ve served by your HTTP server instead:

import { init, Wasmer } from "@wasmer/sdk";
import wasmUrl from "@wasmer/sdk/dist/wasmer_js_bg.wasm?url";

await init(wasmUrl); // This inits the SDK with a custom URL

Using a JS with the Wasm bundled

You can also load Wasmer-JS with a js file with the Wasmer SDK WebAssembly file bundled into it (using bas64 encoding), so no extra requests are required. If that’s your use case, you can simply import @wasmer/sdk/dist/WasmerSDKBundled.js instead:

import { init, Wasmer } from "@wasmer/sdk/dist/WasmerSDKBundled.js";

await init(); // This inits the SDK in the bundled version

Cross-Origin Isolation

Browsers have implemented security measures to mitigate the Spectre and Meltdown vulnerabilities.

These measures restrict the sharing of `SharedArrayBuffer“ objects with Web Workers unless the execution context is deemed secure.

The @wasmer/sdk package uses a threadpool built on Web Workers and requires sharing the same SharedArrayBuffer across multiple workers to enable WASIX threads to access the same address space. This requirement is crucial even for running single-threaded WASIX programs because the SDK internals rely on SharedArrayBuffer for communication with Web Workers.

To avoid Cross-Origin Isolation issues, make sure any web pages using @wasmer/sdk are served over HTTPS and have the following headers set:

"Cross-Origin-Opener-Policy": "same-origin"
"Cross-Origin-Embedder-Policy": "require-corp"

See the SharedArrayBuffer and Cross-Origin Isolation section under the Troubleshooting Common Problems docs for more.

Features

The Wasmer SDK Javascript Package supports:

• WASI support
  • Environment variables
  • FileSystem access
  • Command-line arguments
  • Stdio
• WASIX support
  • Multi-threading
  • Spawning sub-processes
  • Networking (on the works)
• Mounting directories inside the WASIX instance
• Running packages from the Wasmer Registry
• Platforms
  • Browser
  • NodeJS
  • Deno

License

The entire project is under the MIT License. Please read the LICENSE file.