The Wasmer JavaScript SDK

Isomorphic Javascript library for running WASI programs.

The Javascript Package supports:

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

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@3.12");
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}`);

Install from CDN

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@3.12";
          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>

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.

License

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