# @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.