WebAssembly System Interface (WASI) | Node.js v12.18.2 Documentation

Node.js

- About these Docs
- Usage & Example

- Assertion Testing
- Async Hooks
- Buffer
- C++ Addons
- C/C++ Addons with N-API
- Child Processes
- Cluster
- Command Line Options
- Console
- Crypto
- Debugger
- Deprecated APIs
- DNS
- Domain
- ECMAScript Modules
- Errors
- Events
- File System
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules
- Net
- OS
- Path
- Performance Hooks
- Policies
- Process
- Punycode
- Query Strings
- Readline
- REPL
- Report
- Stream
- String Decoder
- Timers
- TLS/SSL
- Trace Events
- TTY
- UDP/Datagram
- URL
- Utilities
- V8
- VM
- WASI
- Worker Threads
- Zlib

- GitHub Repo & Issue Tracker

# WebAssembly System Interface (WASI)#

Stability: 1 - Experimental

The WASI API provides an implementation of the WebAssembly System Interface specification. WASI gives sandboxed WebAssembly applications access to the underlying operating system via a collection of POSIX-like functions.

    'use strict';
    const fs = require('fs');
    const { WASI } = require('wasi');
    const wasi = new WASI({
      args: process.argv,
      env: process.env,
      preopens: {
        '/sandbox': '/some/real/path/that/wasm/can/access'
      }
    });
    const importObject = { wasi_snapshot_preview1: wasi.wasiImport };

    (async () => {
      const wasm = await WebAssembly.compile(fs.readFileSync('./binary.wasm'));
      const instance = await WebAssembly.instantiate(wasm, importObject);

      wasi.start(instance);
    })();

The `--experimental-wasi-unstable-preview1` and `--experimental-wasm-bigint` CLI arguments are needed for the previous example to run.

## Class: `WASI`#

Added in: v12.16.0

The `WASI` class provides the WASI system call API and additional convenience methods for working with WASI-based applications. Each `WASI` instance represents a distinct sandbox environment. For security purposes, each `WASI` instance must have its command line arguments, environment variables, and sandbox directory structure configured explicitly.

### `new WASI([options])`#

Added in: v12.16.0

- `options` <Object>

  - `args` <Array> An array of strings that the WebAssembly application will see as command line arguments. The first argument is the virtual path to the WASI command itself. Default: `[]`.
  - `env` <Object> An object similar to `process.env` that the WebAssembly application will see as its environment. Default: `{}`.
  - `preopens` <Object> This object represents the WebAssembly application's sandbox directory structure. The string keys of `preopens` are treated as directories within the sandbox. The corresponding values in `preopens` are the real paths to those directories on the host machine.
  - `returnOnExit` <boolean> By default, WASI applications terminate the Node.js process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process. Default: `false`.

### `wasi.start(instance)`#

Added in: v12.16.0

- `instance` <WebAssembly.Instance>

Attempt to begin execution of `instance` as a WASI command by invoking its `_start()` export. If `instance` does not contain a `_start()` export, or if `instance` contains an `_initialize()` export, then an exception is thrown.

`start()` requires that `instance` exports a `WebAssembly.Memory` named `memory`. If `instance` does not have a `memory` export an exception is thrown.

If `start()` is called more than once, an exception is thrown.

### `wasi.wasiImport`#

Added in: v12.16.0

- <Object>

`wasiImport` is an object that implements the WASI system call API. This object should be passed as the `wasi_snapshot_preview1` import during the instantiation of a `WebAssembly.Instance`.