emnapi: Node-API for WebAssembly

Common errors

• Error: Cannot find module '@emnapi/runtime'

  cause The `@emnapi/runtime` package, which provides the necessary JavaScript glue code for emnapi-compiled WASM modules, has not been installed or is not resolvable.
  fix Run `npm install @emnapi/runtime` to add the required runtime dependency to your project's `node_modules`.

• WebAssembly.instantiate(): Imports argument must be an object

  cause The import object provided to `WebAssembly.instantiate` is missing the `napi` property, or the value for `napi` is not the object returned by `getNapiRuntime()`.
  fix Ensure you correctly pass the `napi` object as an import, for example: `await WebAssembly.instantiate(wasmBytes, { napi: getNapiRuntime() });`

• WASM memory allocation failed during napi_adjust_external_memory (or similar memory errors)

  cause With emnapi v1.10.0+, `napi_adjust_external_memory` no longer extends WebAssembly memory. Attempts to rely on it for growth will fail silently or result in memory exhaustion if the module needs more memory than initially allocated.
  fix In your C/C++ code, explicitly manage WebAssembly memory growth or ensure the initial memory allocation (`-s INITIAL_MEMORY=...`) is sufficient for your application's needs, especially for versions `1.10.0` and above.

Warnings

• breaking As of v1.10.0, the `napi_adjust_external_memory` function no longer attempts to grow WebAssembly memory. If your application previously relied on this function to expand WASM memory, it will now fail to do so, potentially causing memory allocation errors.
  Fix: Applications must now explicitly manage WebAssembly memory growth or pre-allocate sufficient memory. Do not depend on `napi_adjust_external_memory` for memory expansion; it is solely for notifying the runtime about external memory usage.
• gotcha The `emnapi` npm package serves primarily as a development and build-time dependency. To actually execute emnapi-compiled WebAssembly modules in a JavaScript runtime, you *must* also install either `@emnapi/runtime` (for Emscripten-based builds) or `@emnapi/core` (for non-Emscripten WASM environments) as a separate runtime dependency. Failing to do so will result in module loading failures at runtime.
  Fix: Ensure that `npm install @emnapi/runtime` (or `@emnapi/core`) is explicitly added to your project's dependencies alongside `emnapi` itself.
• gotcha Versions of emnapi prior to v1.9.0 contained known data race and use-after-free vulnerabilities within its `napi_threadsafe_function` implementation. These issues could lead to unpredictable behavior, crashes, or incorrect results, particularly in multi-threaded WebAssembly scenarios.
  Fix: It is critical to upgrade to emnapi v1.9.0 or any later version to mitigate these severe concurrency bugs and ensure the stability and correctness of `napi_threadsafe_function` usage.
• gotcha emnapi requires specific versions of its prerequisites, including Node.js (>= v16.15.0), npm (>= v8), and Emscripten (>= v3.1.9) or compatible WASI SDK/LLVM clang versions. Using outdated or incompatible versions can lead to build failures, unexpected runtime errors, or incorrect behavior.
  Fix: Always consult the official emnapi documentation's 'Prerequisites' section to confirm your development environment meets all specified version requirements for Node.js, npm, and Emscripten/WASI SDK.

Install

• npm install emnapi npm
• yarn add emnapi yarn
• pnpm add emnapi pnpm

Imports

• getNapiRuntime
  wrong:

  const { getNapiRuntime } = require('emnapi');

  correct:

  import { getNapiRuntime } from 'emnapi';

  This function retrieves the emnapi N-API runtime object, essential for WebAssembly module instantiation. The `emnapi` package itself is often a dev/build dependency, while `@emnapi/runtime` is the primary JavaScript runtime dependency for client-side usage.
• emnapiCtx
  wrong:

  const emnapiCtx = require('emnapi').emnapiCtx;

  correct:

  import { emnapiCtx } from 'emnapi';

  Provides the low-level Emscripten N-API context. Direct interaction is typically for advanced use cases or debugging.
• NapiRuntime
  wrong:

  import { NapiRuntime } from 'emnapi';

  correct:

  import type { NapiRuntime } from 'emnapi';

  Used for type hinting the return value of `getNapiRuntime` or other emnapi-related objects in TypeScript projects, ensuring type safety without importing a value at runtime.

Quickstart

This quickstart demonstrates how to load a WebAssembly module (e.g., `hello.wasm`) compiled with emnapi, instantiate it in a Node.js environment using the `emnapi` runtime, and invoke an exported function from JavaScript/TypeScript.

import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
import { getNapiRuntime } from 'emnapi';

// In a CommonJS environment, replace 'import.meta.url' with '__filename' and 'dirname(fileURLToPath(...))' with '__dirname'.
const currentModuleDir = typeof __dirname !== 'undefined' ? __dirname : dirname(fileURLToPath(import.meta.url));

// Assuming 'hello.wasm' is compiled from C/C++ using emnapi and placed next to this script.
const wasmPath = join(currentModuleDir, './hello.wasm');
const wasmBytes = readFileSync(wasmPath);

async function runWasmModule() {
  try {
    // Initialize the emnapi runtime for the WebAssembly instance
    const napi = getNapiRuntime();

    // Instantiate the WebAssembly module with the emnapi imports
    // The 'napi' object is crucial for providing the N-API environment to the WASM module.
    const { instance } = await WebAssembly.instantiate(wasmBytes, { napi });

    // Access exported functions from the WASM module
    // For a simple 'hello world' N-API module compiled with emnapi, it might expose a function like 'hello'.
    // The exact function name depends on your C/C++ N-API addon's exports.
    const helloFunction = instance.exports.hello; // Replace 'hello' with your actual exported function name

    if (typeof helloFunction === 'function') {
      const result = helloFunction();
      console.log('Result from WASM module:', result); // Expected output might be 'world' or similar
    } else {
      console.error('The exported function "hello" was not found or is not a function in the WASM module.');
    }
  } catch (err) {
    console.error('Failed to load or run WASM module with emnapi:', err);
  }
}

runWasmModule();