Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getNapiRuntime
✓ import { getNapiRuntime } from 'emnapi';
✗ const { getNapiRuntime } = require('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
✓ import { emnapiCtx } from 'emnapi';
✗ const emnapiCtx = require('emnapi').emnapiCtx;
Provides the low-level Emscripten N-API context. Direct interaction is typically for advanced use cases or debugging.
NapiRuntime
✓ import type { NapiRuntime } from 'emnapi';
✗ import { 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.
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();
Errors
Common errors & fixes
Error: Cannot find module '@emnapi/runtime'
The `@emnapi/runtime` package, which provides the necessary JavaScript glue code for emnapi-compiled WASM modules, has not been installed or is not resolvable.
fixRun `npm install @emnapi/runtime` to add the required runtime dependency to your project's `node_modules`.
WebAssembly.instantiate(): Imports argument must be an object
The import object provided to `WebAssembly.instantiate` is missing the `napi` property, or the value for `napi` is not the object returned by `getNapiRuntime()`.
fixEnsure 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)
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.
fixIn 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.
Audit
Dependencies
node-addon-apioptionalPeer dependency for C++ Node-API development, providing convenient C++ wrappers for N-API.
@emnapi/runtimerequiredRequired at runtime in JavaScript environments to load and interact with emnapi-compiled WebAssembly modules, especially when using Emscripten.
@emnapi/coreoptionalAn alternative runtime for non-Emscripten WASM environments where Node-API is needed.