@napi-rs/cli 3.8.1 → 3.8.3

package/docs/wasi.md

@@ -153,9 +153,45 @@ module runs inside the host process, so `wasm32` or host-OS restrictions would
 make npm reject a direct install or skip the optional dependency on otherwise
 supported hosts.
 
+Because nothing gates the install, the root package does not declare the WASI
+package in `optionalDependencies` when native targets are also configured. npm
+evaluates every `optionalDependencies` entry independently, so a declared WASI
+package is downloaded by every consumer, including the ones that already
+resolved a native package and will never load the `.wasm` binary. The generated
+binding loader picks WASI at require time instead, and environments without a
+native package are expected to install it on demand.
+
+When WASI is the only configured target it is the primary artifact rather than a
+fallback, so it is declared by default. Set `napi.wasm.optionalDependency` to
+override the default in either direction:
+
+```json
+{
+  "napi": {
+    "wasm": {
+      "optionalDependency": true
+    }
+  }
+}
+```
+
 `napi.wasm.initialMemory` is measured in 64 KiB WebAssembly pages. The regular
 Node and browser loaders retain the historical 4,000-page (250 MiB) default.
 The deferred `./workerd` loader defaults to 1,024 pages (64 MiB), leaving
 headroom under workerd's 128 MiB isolate limit. An explicit
 `napi.wasm.initialMemory` value applies to every loader, so keep it within the
 target isolate's limit after measuring the addon's actual requirements.
+
+Threaded browser loaders always pre-create a pool of wasi-threads workers at
+module initialization, sized as `asyncWorkPoolSize + hardwareConcurrency`
+(logical cores, floored at 2, with a fallback for privacy-fuzzed values),
+and therefore always initialize asynchronously. The `asyncWorkPoolSize`
+reservation is included because emnapi's async-work pool draws its workers
+from the same reuse pool; without it, async work could starve the pool
+before addon thread spawns. This is what allows addon Rust code to spawn
+threads from inside a blocking call: a browser cannot start a worker until
+the blocking thread returns to its event loop, so a thread spawned mid-call
+would never boot and the caller would deadlock waiting for it. With a
+pre-created pool, spawning is only a message to an already-running worker,
+and if the pool is exhausted the fallback allocates a fresh worker that
+boots once the spawning parent returns to its event loop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/cli",
-  "version": "3.8.1",
+  "version": "3.8.3",
   "description": "Cli tools for napi-rs",
   "author": "LongYinan <lynweklm@gmail.com>",
   "homepage": "https://napi.rs/",
@@ -86,7 +86,7 @@
     "ava": "^8.0.1",
     "empathic": "^2.0.1",
     "env-paths": "^4.0.0",
-    "oxc-parser": "^0.142.0",
+    "oxc-parser": "^0.143.0",
     "prettier": "^3.8.3",
     "tsdown": "^0.22.2",
     "tslib": "^2.8.1"

package/src/api/__tests__/__snapshots__/templates.spec.ts.md

@@ -12,7 +12,7 @@ Generated by [AVA](https://avajs.dev).
       emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,␊
       emnapiTSFNPlugin as __emnapiTSFNPlugin,␊
       createOnMessage as __wasmCreateOnMessageForFsProxy,␊
-      instantiateNapiModuleSync as __emnapiInstantiateNapiModuleSync,␊
+      instantiateNapiModule as __emnapiInstantiateNapiModule,␊
       WASI as __WASI,␊
     } from '@napi-rs/wasm-runtime'␊
     import { createContext as __emnapiCreateContext } from '@emnapi/runtime'␊
@@ -42,6 +42,11 @@ Generated by [AVA](https://avajs.dev).
       maximum: 65536,␊
       shared: true,␊
     })␊
+    const __asyncWorkPoolSize = 4␊
+    const __workerPoolSize = Math.max(␊
+      2,␊
+      globalThis.navigator?.hardwareConcurrency ?? 4,␊
+    )␊
     ␊
     let __emnapiContext␊
     ␊
@@ -314,9 +319,10 @@ Generated by [AVA](https://avajs.dev).
         instance: __napiInstance,␊
         module: __wasiModule,␊
         napiModule: __napiModule,␊
-      } = __emnapiInstantiateNapiModuleSync(__wasmFile, {␊
+      } = await __emnapiInstantiateNapiModule(__wasmFile, {␊
         context: __emnapiContext,␊
-        asyncWorkPoolSize: 4,␊
+        asyncWorkPoolSize: __asyncWorkPoolSize,␊
+        reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
         plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊
@@ -361,7 +367,7 @@ Generated by [AVA](https://avajs.dev).
       emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,␊
       emnapiTSFNPlugin as __emnapiTSFNPlugin,␊
       createOnMessage as __wasmCreateOnMessageForFsProxy,␊
-      instantiateNapiModuleSync as __emnapiInstantiateNapiModuleSync,␊
+      instantiateNapiModule as __emnapiInstantiateNapiModule,␊
       WASI as __WASI,␊
     } from '@napi-rs/wasm-runtime'␊
     import { createContext as __emnapiCreateContext } from '@emnapi/runtime'␊
@@ -391,6 +397,11 @@ Generated by [AVA](https://avajs.dev).
       maximum: 65536,␊
       shared: true,␊
     })␊
+    const __asyncWorkPoolSize = 4␊
+    const __workerPoolSize = Math.max(␊
+      2,␊
+      globalThis.navigator?.hardwareConcurrency ?? 4,␊
+    )␊
     ␊
     let __emnapiContext␊
     ␊
@@ -663,9 +674,10 @@ Generated by [AVA](https://avajs.dev).
         instance: __napiInstance,␊
         module: __wasiModule,␊
         napiModule: __napiModule,␊
-      } = __emnapiInstantiateNapiModuleSync(__wasmFile, {␊
+      } = await __emnapiInstantiateNapiModule(__wasmFile, {␊
         context: __emnapiContext,␊
-        asyncWorkPoolSize: 4,␊
+        asyncWorkPoolSize: __asyncWorkPoolSize,␊
+        reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
         plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊
@@ -723,7 +735,7 @@ Generated by [AVA](https://avajs.dev).
       emnapiAsyncWorkPlugin as __emnapiAsyncWorkPlugin,␊
       emnapiTSFNPlugin as __emnapiTSFNPlugin,␊
       createOnMessage as __wasmCreateOnMessageForFsProxy,␊
-      instantiateNapiModuleSync as __emnapiInstantiateNapiModuleSync,␊
+      instantiateNapiModule as __emnapiInstantiateNapiModule,␊
       WASI as __WASI,␊
     } from '@napi-rs/wasm-runtime'␊
     import { createContext as __emnapiCreateContext } from '@emnapi/runtime'␊
@@ -759,6 +771,11 @@ Generated by [AVA](https://avajs.dev).
       maximum: 65536,␊
       shared: true,␊
     })␊
+    const __asyncWorkPoolSize = 4␊
+    const __workerPoolSize = Math.max(␊
+      2,␊
+      globalThis.navigator?.hardwareConcurrency ?? 4,␊
+    )␊
     ␊
     let __emnapiContext␊
     ␊
@@ -1031,9 +1048,10 @@ Generated by [AVA](https://avajs.dev).
         instance: __napiInstance,␊
         module: __wasiModule,␊
         napiModule: __napiModule,␊
-      } = __emnapiInstantiateNapiModuleSync(__wasmFile, {␊
+      } = await __emnapiInstantiateNapiModule(__wasmFile, {␊
         context: __emnapiContext,␊
-        asyncWorkPoolSize: 4,␊
+        asyncWorkPoolSize: __asyncWorkPoolSize,␊
+        reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },␊
         plugins: [__emnapiAsyncWorkPlugin, __emnapiTSFNPlugin],␊
         wasi: __wasi,␊
         onCreateWorker() {␊

package/src/api/__tests__/pre-publish.spec.ts

@@ -0,0 +1,141 @@
+import test from 'ava'
+
+import {
+  parseNpmPackFiles,
+  resolveRootOptionalDependencies,
+} from '../pre-publish.js'
+import { parseTriple } from '../../utils/index.js'
+
+const PACKAGE_NAME = '@scope/pkg'
+const VERSION = '1.2.3'
+
+const NATIVE_TARGETS = ['aarch64-apple-darwin', 'x86_64-unknown-linux-gnu'].map(
+  parseTriple,
+)
+const WASI_TARGET = parseTriple('wasm32-wasip1-threads')
+const THREADLESS_WASI_TARGET = parseTriple('wasm32-wasip1')
+
+const NATIVE_ENTRIES = {
+  [`${PACKAGE_NAME}-darwin-arm64`]: VERSION,
+  [`${PACKAGE_NAME}-linux-x64-gnu`]: VERSION,
+}
+
+function resolve(
+  targets: Parameters<typeof resolveRootOptionalDependencies>[0]['targets'],
+  overrides: Partial<
+    Parameters<typeof resolveRootOptionalDependencies>[0]
+  > = {},
+) {
+  return resolveRootOptionalDependencies({
+    existing: undefined,
+    managedPackageNames: [PACKAGE_NAME],
+    packageName: PACKAGE_NAME,
+    targets,
+    version: VERSION,
+    ...overrides,
+  })
+}
+
+test('omits the WASI package when native targets are configured', (t) => {
+  // The WASI binary is a require-time fallback, not something npm should
+  // install on hosts that already resolved a native package.
+  t.deepEqual(resolve([...NATIVE_TARGETS, WASI_TARGET]), NATIVE_ENTRIES)
+})
+
+test('omits the threadless WASI package too', (t) => {
+  t.deepEqual(
+    resolve([...NATIVE_TARGETS, THREADLESS_WASI_TARGET]),
+    NATIVE_ENTRIES,
+  )
+})
+
+test('declares the WASI package when it is the only target', (t) => {
+  // With no native package to fall back from, WASI is the primary artifact.
+  t.deepEqual(resolve([WASI_TARGET]), {
+    [`${PACKAGE_NAME}-wasm32-wasi`]: VERSION,
+  })
+})
+
+test('declares every WASI flavor when only WASI targets are configured', (t) => {
+  t.deepEqual(resolve([WASI_TARGET, THREADLESS_WASI_TARGET]), {
+    [`${PACKAGE_NAME}-wasm32-wasi`]: VERSION,
+    [`${PACKAGE_NAME}-wasm32-wasip1`]: VERSION,
+  })
+})
+
+test('wasm.optionalDependency=true opts back into declaring WASI', (t) => {
+  t.deepEqual(
+    resolve([...NATIVE_TARGETS, WASI_TARGET], {
+      wasm: { optionalDependency: true },
+    }),
+    {
+      ...NATIVE_ENTRIES,
+      [`${PACKAGE_NAME}-wasm32-wasi`]: VERSION,
+    },
+  )
+})
+
+test('wasm.optionalDependency=false opts out even for WASI-only builds', (t) => {
+  t.deepEqual(
+    resolve([WASI_TARGET], { wasm: { optionalDependency: false } }),
+    {},
+  )
+})
+
+test('drops a stale WASI entry left over from a previous release', (t) => {
+  // Consumers upgrading from a release that did declare the WASI package must
+  // not keep the entry, otherwise the regression survives the fix.
+  t.deepEqual(
+    resolve([...NATIVE_TARGETS, WASI_TARGET], {
+      existing: {
+        ...NATIVE_ENTRIES,
+        [`${PACKAGE_NAME}-wasm32-wasi`]: '1.2.2',
+      },
+    }),
+    NATIVE_ENTRIES,
+  )
+})
+
+test('preserves unmanaged optionalDependencies', (t) => {
+  t.deepEqual(
+    resolve([...NATIVE_TARGETS, WASI_TARGET], {
+      existing: { 'unrelated-package': '^1.0.0' },
+    }),
+    {
+      'unrelated-package': '^1.0.0',
+      ...NATIVE_ENTRIES,
+    },
+  )
+})
+
+const NPM_PACK_FILES = [
+  { path: './package.json' },
+  { path: 'dist\\index.js' },
+  { path: 42 },
+]
+
+test('parses npm 11 pack JSON output', (t) => {
+  t.deepEqual(
+    [...parseNpmPackFiles(JSON.stringify([{ files: NPM_PACK_FILES }]))],
+    ['package.json', 'dist/index.js'],
+  )
+})
+
+test('parses npm 12 pack JSON output', (t) => {
+  t.deepEqual(
+    [
+      ...parseNpmPackFiles(
+        JSON.stringify({
+          [PACKAGE_NAME]: { files: NPM_PACK_FILES },
+        }),
+      ),
+    ],
+    ['package.json', 'dist/index.js'],
+  )
+})
+
+test('rejects an unexpected npm pack JSON result', (t) => {
+  t.throws(() => parseNpmPackFiles(JSON.stringify({ files: [] })), {
+    message: 'npm pack returned an unexpected JSON result',
+  })
+})

package/src/api/__tests__/templates.spec.ts

@@ -13,6 +13,54 @@ test('createWasiBrowserBinding default', (t) => {
   t.snapshot(createWasiBrowserBinding('test-wasi'))
 })
 
+test('createWasiBrowserBinding threaded builds size worker pools from hardwareConcurrency', (t) => {
+  const binding = createWasiBrowserBinding(
+    'test-wasi',
+    4000,
+    65536,
+    false,
+    false, // asyncInit: false — threaded builds still init asynchronously
+    false,
+    false,
+    true,
+  )
+  t.true(binding.includes('const __asyncWorkPoolSize = 4'))
+  t.true(binding.includes('const __workerPoolSize = Math.max('))
+  t.true(binding.includes('globalThis.navigator?.hardwareConcurrency ?? 4'))
+  // The reuse pool includes the async-work reservation: the async pool
+  // draws from the same reuse pool, so without it exhaustion would starve
+  // addon thread spawns. No `strict`: at exhaustion the fallback worker
+  // boots once the parent returns to its event loop, which is the correct
+  // behavior for spawn-and-return workloads.
+  t.true(
+    binding.includes(
+      'reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },',
+    ),
+  )
+  t.false(binding.includes('strict'))
+  t.true(binding.includes('asyncWorkPoolSize: __asyncWorkPoolSize,'))
+  t.true(binding.includes('await __emnapiInstantiateNapiModule('))
+  t.false(binding.includes('__emnapiInstantiateNapiModuleSync(__wasmFile'))
+})
+
+test('createWasiBrowserBinding threadless keeps sync init and no pool', (t) => {
+  const binding = createWasiBrowserBinding(
+    'test-wasi',
+    4000,
+    65536,
+    false,
+    false,
+    false,
+    false,
+    false,
+  )
+  t.false(binding.includes('__workerPoolSize'))
+  t.false(binding.includes('hardwareConcurrency'))
+  t.false(binding.includes('reuseWorker'))
+  t.true(binding.includes('asyncWorkPoolSize: 0,'))
+  t.true(binding.includes('__emnapiInstantiateNapiModuleSync(__wasmFile'))
+})
+
 test('createWasiBrowserBinding with errorEvent', (t) => {
   t.snapshot(
     createWasiBrowserBinding(

package/src/api/pre-publish.ts

@@ -60,6 +60,7 @@ import {
   type CommonPackageJsonFields,
   type FileSystemTransactionWrite,
   type Target,
+  type UserNapiConfig,
 } from '../utils/index.js'
 
 const debug = debugFactory('pre-publish')
@@ -227,6 +228,61 @@ async function copyOwnedTemporaryPath(source: string, destination: string) {
   }
 }
 
+function wasiIsOnlyTarget(targets: Target[]) {
+  return (
+    targets.length > 0 && targets.every((target) => target.platform === 'wasi')
+  )
+}
+
+/**
+ * Build the root package's `optionalDependencies` map.
+ *
+ * A WASI package is a fallback for hosts that cannot load a `.node` binary, and
+ * the generated binding loader selects it at require time rather than npm
+ * selecting it at install time. Declaring it as an `optionalDependency`
+ * alongside the native packages cannot express "install this only when nothing
+ * else matched": npm evaluates every entry independently, so every consumer
+ * downloads a `.wasm` binary they will never load.
+ *
+ * It is therefore only declared when WASI is the only configured target, which
+ * makes it the primary artifact rather than a fallback.
+ * `napi.wasm.optionalDependency` overrides the default in both directions.
+ *
+ * See https://github.com/rolldown/rolldown/issues/10556
+ */
+export function resolveRootOptionalDependencies({
+  existing,
+  managedPackageNames,
+  packageName,
+  targets,
+  version,
+  wasm,
+}: {
+  existing: unknown
+  managedPackageNames: Iterable<string>
+  packageName: string
+  targets: Target[]
+  version: string
+  wasm?: UserNapiConfig['wasm']
+}): Record<string, unknown> {
+  const optionalDependencies: Record<string, unknown> = {
+    ...asRecord(existing),
+  }
+  for (const managedPackageName of managedPackageNames) {
+    for (const suffix of MANAGED_OPTIONAL_DEPENDENCY_SUFFIXES) {
+      delete optionalDependencies[`${managedPackageName}-${suffix}`]
+    }
+  }
+  const declareWasi = wasm?.optionalDependency ?? wasiIsOnlyTarget(targets)
+  for (const target of targets) {
+    if (target.platform === 'wasi' && !declareWasi) {
+      continue
+    }
+    optionalDependencies[`${packageName}-${target.platformArchABI}`] = version
+  }
+  return optionalDependencies
+}
+
 export async function prePublish(userOptions: PrePublishOptions) {
   debug('Receive pre-publish options:')
   debug('  %O', userOptions)
@@ -341,9 +397,6 @@ export async function prePublish(userOptions: PrePublishOptions) {
             rootFacade,
           )
         }
-        const optionalDependencies = {
-          ...asRecord(packageJson.optionalDependencies),
-        }
         const managedPackageNames = new Set([packageName])
         for (const flavorPackage of rootFacadeReconciliation.managedFlavorPackages) {
           for (const suffix of MANAGED_OPTIONAL_DEPENDENCY_SUFFIXES) {
@@ -353,22 +406,19 @@ export async function prePublish(userOptions: PrePublishOptions) {
             }
           }
         }
-        for (const managedPackageName of managedPackageNames) {
-          for (const suffix of MANAGED_OPTIONAL_DEPENDENCY_SUFFIXES) {
-            delete optionalDependencies[`${managedPackageName}-${suffix}`]
-          }
-        }
-        for (const target of targets) {
-          optionalDependencies[`${packageName}-${target.platformArchABI}`] =
-            packageJson.version
-        }
-        const nodeEngine =
-          targets.length > 0 &&
-          targets.every((target) => target.platform === 'wasi')
-            ? restrictWasiNodeEngine(
-                packageJson.engines?.node ?? MINIMUM_WASI_NODE_VERSION,
-              )
-            : undefined
+        const optionalDependencies = resolveRootOptionalDependencies({
+          existing: packageJson.optionalDependencies,
+          managedPackageNames,
+          packageName,
+          targets,
+          version: packageJson.version,
+          wasm,
+        })
+        const nodeEngine = wasiIsOnlyTarget(targets)
+          ? restrictWasiNodeEngine(
+              packageJson.engines?.node ?? MINIMUM_WASI_NODE_VERSION,
+            )
+          : undefined
         const rootReleasePlan: RootReleaseMaterializationPlan = {
           packageJson: reconciledPackageJson,
           optionalDependencies,
@@ -1641,18 +1691,7 @@ function readNpmPackFiles(packageDir: string, packageDescription: string) {
       maxBuffer: 64 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'pipe'],
     })
-    const packResult = JSON.parse(output) as {
-      files?: { path?: unknown }[]
-    }[]
-    if (!Array.isArray(packResult) || !Array.isArray(packResult[0]?.files)) {
-      throw new Error('npm pack returned an unexpected JSON result')
-    }
-    return new Set(
-      packResult[0].files
-        .map(({ path }) => path)
-        .filter((path): path is string => typeof path === 'string')
-        .map((path) => path.replaceAll('\\', '/').replace(/^\.\//, '')),
-    )
+    return parseNpmPackFiles(output)
   } catch (error) {
     throw new Error(
       `Failed to validate the ${packageDescription} with npm pack --dry-run. Ensure npm is available and the package can be packed.`,
@@ -1661,6 +1700,23 @@ function readNpmPackFiles(packageDir: string, packageDescription: string) {
   }
 }
 
+export function parseNpmPackFiles(output: string) {
+  const parsedResult: unknown = JSON.parse(output)
+  const packResults = Array.isArray(parsedResult)
+    ? parsedResult
+    : Object.values(asRecord(parsedResult) ?? {})
+  const files = asRecord(packResults[0])?.files
+  if (!Array.isArray(files)) {
+    throw new Error('npm pack returned an unexpected JSON result')
+  }
+  return new Set(
+    files
+      .map((file) => asRecord(file)?.path)
+      .filter((path): path is string => typeof path === 'string')
+      .map((path) => path.replaceAll('\\', '/').replace(/^\.\//, '')),
+  )
+}
+
 function validateRootFacadePacklist(
   rootDir: string,
   rootPackageFiles: string[],

package/src/api/templates/load-wasi-template.ts

@@ -271,6 +271,10 @@ export const createWasiBrowserBinding = (
   errorEvent = false,
   threads = true,
 ) => {
+  // Threaded builds always get a pre-created worker pool (see
+  // `reuseWorkerOption` below), and pool pre-creation is asynchronous, so
+  // they always initialize asynchronously.
+  const effectiveAsyncInit = asyncInit || threads
   const fsImport = fs
     ? buffer
       ? `import { memfs, Buffer } from '@napi-rs/wasm-runtime/fs'`
@@ -317,17 +321,55 @@ const __wasi = new __WASI({
   const emnapiInjectBuffer = buffer
     ? '  __emnapiContext.features.Buffer = Buffer\n'
     : ''
-  const emnapiInstantiateImport = asyncInit
+  const emnapiInstantiateImport = effectiveAsyncInit
     ? `instantiateNapiModule as __emnapiInstantiateNapiModule`
     : `instantiateNapiModuleSync as __emnapiInstantiateNapiModuleSync`
-  const emnapiInstantiateCall = asyncInit
+  const emnapiInstantiateCall = effectiveAsyncInit
     ? `await __emnapiInstantiateNapiModule`
     : `__emnapiInstantiateNapiModuleSync`
+  // The `reuseWorker` pool is what lets addon Rust code spawn threads while
+  // the calling thread is blocked inside the wasm call: a browser cannot
+  // start a worker until the blocking thread returns to its event loop, so
+  // a thread spawned mid-call can never boot and the caller deadlocks
+  // waiting for it. With a pre-created pool, spawning is only a message to
+  // an already-running worker.
+  //
+  // Its size comes from `navigator.hardwareConcurrency` at runtime (logical
+  // cores, floored at 2, with a fallback for privacy-fuzzed or missing
+  // values): a constant undersizes both ends of the range — big desktops
+  // leave parallelism on the table, and a fuzzed "2 cores" would
+  // oversubscribe.
+  //
+  // The reuse pool is sized as `__asyncWorkPoolSize + __workerPoolSize`
+  // because emnapi's async-work pool draws its workers from the SAME reuse
+  // pool: the async reservation must be included or async-work
+  // initialization can starve the reuse pool before addon threads spawn.
+  //
+  // `strict` is deliberately NOT set. Review suggested it so exhaustion
+  // errors instead of allocating a fresh worker, but it breaks
+  // spawn-and-return workloads (e.g. `testWorkers` in examples/napi, which
+  // spawns workers and joins them on a helper thread): at exhaustion their
+  // `std::thread::spawn` panics on EAGAIN. Without `strict` the fallback
+  // allocates a fresh worker, which boots normally once the spawning
+  // parent returns to its event loop — and for joins inside a blocked
+  // call, the pre-created pool is what those calls draw from anyway.
+  const workerPoolSizeBinding = threads
+    ? `const __asyncWorkPoolSize = 4
+const __workerPoolSize = Math.max(
+  2,
+  globalThis.navigator?.hardwareConcurrency ?? 4,
+)
+
+`
+    : ''
+  const reuseWorkerOption = threads
+    ? `    reuseWorker: { size: __asyncWorkPoolSize + __workerPoolSize },\n`
+    : ''
   const workerRuntimeImport = threads
     ? `  createOnMessage as __wasmCreateOnMessageForFsProxy,\n`
     : ''
   const memoryName = threads ? '__sharedMemory' : '__wasmMemory'
-  const asyncWorkPoolOption = `    asyncWorkPoolSize: ${threads ? 4 : 0},
+  const asyncWorkPoolOption = `    asyncWorkPoolSize: ${threads ? '__asyncWorkPoolSize' : 0},
 `
   // Every build links a "basic" emnapi archive without the C async-work and
   // threadsafe-function implementations (the `emnapi-napi-rs(-mt)` archives shipped by the emnapi package), so the
@@ -380,7 +422,7 @@ const ${memoryName} = new WebAssembly.Memory({
   maximum: ${maximumMemory},
 ${threads ? '  shared: true,\n' : ''}\
 })
-
+${workerPoolSizeBinding}\
 let __emnapiContext
 ${emnapiContextLifecycle}
 let __wasiModule
@@ -397,6 +439,7 @@ try {
   } = ${emnapiInstantiateCall}(__wasmFile, {
     context: __emnapiContext,
 ${asyncWorkPoolOption}\
+${reuseWorkerOption}\
 ${emnapiPluginOption}\
     wasi: __wasi,
 ${workerOption}\

package/src/utils/config.ts

@@ -72,10 +72,29 @@ export interface UserNapiConfig {
      */
     maximumMemory?: number
 
+    /**
+     * Whether the generated `<packageName>-wasm32-wasi` package is declared as
+     * an `optionalDependency` of the root package.
+     *
+     * When native targets are configured the WASI package is a fallback for
+     * hosts that cannot load a `.node` binary, so declaring it would make every
+     * consumer download the `.wasm` binary they will never load. It is
+     * therefore omitted by default and is expected to be installed on demand by
+     * the environments that need it.
+     *
+     * When WASI is the only configured target it is the primary artifact and is
+     * declared by default.
+     *
+     * Set this explicitly to override either default.
+     *
+     * @default true when every configured target is WASI, false otherwise
+     */
+    optionalDependency?: boolean
+
     /**
      * Browser wasm binding configuration
      */
-    browser: {
+    browser?: {
       /**
        * Whether to use fs module in browser
        */