@napi-rs/wasm-runtime
Runtime helpers and browser polyfills for napi-rs WebAssembly addons.
emnapi compatibility
Use matching versions of @emnapi/core and @emnapi/runtime:
- v1:
^1.7.1. Core includes async work and threadsafe functions and ignores the
plugins option. Loading this package does not resolve the v2-only
@emnapi/core/plugins export.
- v2: the peer range is exactly
2.0.0-beta.2 or 2.0.0-beta.3, and this
package bundles the async-work and TSFN plugins from 2.0.0-beta.3. They
depend on private core context fields, which are the same in both betas
(2.0.0-beta.3 changed only the TSFN release order). 2.0.0-beta.1 renamed
the context field napiModule to addonModule; the bundled plugins accept
both names, so bindings that pin a 2.0.0 alpha keep loading. A later
prerelease that changes the context again needs a new release of this
package.
The v2 peer range stays narrow on purpose. With an open range, npm can hoist a
binding's 2.0.0 alpha core next to this package, and then v1 bindings that
load through the ESM entry, or through tools that skip the CommonJS copy
lookup below, get a v2 core. With the narrow range, npm installs a v1 core for
this package when a binding pins another v2 prerelease. The binding's own
emnapi copy still runs it, as described below.
The CommonJS entry keeps emnapi copies apart when this package's peers resolve
to a different copy than a binding's own @emnapi/core and @emnapi/runtime
(two bindings pinning different emnapi versions, say):
instantiateNapiModule(Sync) runs the core of the copy whose runtime created
options.context. It finds that runtime in require.cache and resolves the
core from the module that required it (the binding's loader).
getDefaultContext, createContext, MessageHandler, and instantiation
without a context use the copy of the calling package when it declares both
emnapi packages as dependencies: the CommonJS module that is still loading
and required this package, or, in a worker thread, the worker's entry file.
- When the selected core is v2, the bundled plugins are replaced by that core's
own
@emnapi/core/plugins.
- Anything else uses this package's peers. A context of the other emnapi
generation from no known copy throws a
TypeError that says so.
The ESM entry is resolved by bundlers and cannot do this. It uses the bundled
plugins with the addonModule alias.
For raw instantiateNapiModule / instantiateNapiModuleSync calls loading a
single-threaded napi-rs addon, pass
plugins: [emnapiAsyncWorkPlugin, emnapiTSFNPlugin] from this package. Generated
napi-rs loaders already supply these plugins.
Updating the bundled plugins
Update the exact v2 development dependencies together with the workspace
resolutions. build checks that the resolved core version is the exact
development version and one of the v2 versions in the peer range, and
prepack rebuilds the bundles so a package cannot silently reuse output from
an earlier build. Before a release, compare the new plugin context with the
oldest supported alpha (2.0.0-alpha.3 is the oldest still pinned by published
bindings), and keep the CI matrix covering it. Keep earlier v2 versions in the
peer range while published bindings pin them (rolldown 1.2.16 pins
2.0.0-beta.2); removing one makes npm install a v1 core for this package
next to those bindings.
yarn workspace @napi-rs/wasm-runtime test exercises actual WebAssembly
initialization, async work, TSFN calls from a worker, worker load failures, and
cleanup through both module formats. CI also installs the packed tarball with
real v1 and v2 peers outside the workspace to avoid root resolution overrides.