Seeking for better default vite:wasm plugin

[sapphi-red]

Update: This proposal was implemented by #8219.

original content follwing

---

Current behavior

(a) Import without query (import wasm from 'foo.wasm')

declare module '*.wasm' {
  const initWasm: (options: WebAssembly.Imports) => Promise<WebAssembly.Exports>
  export default initWasm
}

(b) Import with ?url (import wasmUrl from 'foo.wasm?url')

declare module '*?url' {
  const src: string
  export default src
}

(c) Using import.meta.url (new URL('foo.wasm', import.meta.url))

Obtains URL to wasm file. This is not handled by vite:wasm plugin but I'm mentioning this since it is related.

wasm-bindgen (with --target web) and AssemblyScript uses this.

Usecases

1. Wants access to WebAssembly.Instance (#5190, #5615, #3847)

• Emscripten has an instantiateWasm property which requires WebAssembly.Instance.
  • In WebAssembly helper should return the module #5190, it is said as Webassembly.Module, but it is actually WebAssembly.Instance.
• golang's glue code (Go.run) requires WebAssembly.Instance.

2. Wants access to WebAssembly.Module

• Is there any cases which does not require a custom logic?
  • It can be used for caching but I think the requirements differs among people.

3. Wants ArrayBuffer of wasm

• Emscripten has an wasmBinary property which requires ArrayBuffer.
• I think this usage does not need be handled specially. Using (b) or (c) above and fetch is enough.

4. ES Module Integration Proposal for WebAssembly (#4551, #5755)

• wasm-bindgen (with --target bundler) uses this.
• Webpack supports this with experiments.asyncWebAssembly (Example).
• Currently Stage 2 in WebAssembly's process.
• Firefox and Safari are positive to this spec according to Chrome Platform Status
  • But I have not found any information about it for Firefox and Safari. Also it seems there is no active developement in Chrome.
  • It is not supported in Deno. Support importing wasm modules  denoland/deno#2552
  • It is supported in Node.js under the --experimental-wasm-modules flag. It is "Stability 1" and non-backward compatible changes may occur.

Previously proposed approaches

• vite-plugin-wasm: Implements "Usecase 4" above
  • it requires vite-plugin-top-level-await even for modern browsers.
    • This is because top-level await transpile is not supported by esbuild.
    • This plugin processes every chunk so it might slow down the bundle time.
• feat(wasm): option for initWasm() to return the instance (#3847 #5615) #7181: adds getInstance parameter for WebAssembly.Instance

  • declare module '*.wasm' {
      function initWasm(options: WebAssembly.Imports, getInstance: true): Promise<WebAssembly.Instance>
      function initWasm(options: WebAssembly.Imports, getInstance: false): Promise<WebAssembly.Exports> // added
      function initWasm(options: WebAssembly.Imports): Promise<WebAssembly.Exports>
    
      export default initWasm
    }

My proposal

I believe that "ESM integration proposal for Wasm" should not be implemented at the current point. Because the spec is Stage 2 and it is experimental in Node.js which means it may change in future.

import wasm from 'foo.wasm'

Do not handle with vite:wasm.
If it was not handled with any plugin, throw an error that "ESM integration proposal for Wasm" is not supported.
Maybe implement "ESM integration proposal for Wasm" with vite:wasm and only enable it behind experimental option. But it needs to be considered how to get along with top-level await.

This makes users to be able to use other plugins (like vite-plugin-wasm) to handle wasm.

import wasmUrl from 'foo.wasm?url'

Handle it same as currently.

import init from 'foo.wasm?helper'

Handle it same as the current import init from 'foo.wasm' does.

import init from 'foo.wasm?helper'

const imports = {}

init(imports).then(exports => 
  exports.test()
)

declare module '*.wasm?helper' {
  const initWasm: (options: WebAssembly.Imports) => Promise<WebAssembly.Exports>
  export default initWasm
}

The motivation of requiring query is to avoid future conflict with "ESM integration proposal for Wasm".
Also the return value of init is aligned to "ESM integration proposal for Wasm" to make it easy to migrate in future.

import init from 'foo.wasm?instance'

import init from 'foo.wasm?instance'

const imports = {}

init(imports).then(({ instance, module }) =>
  // use module and instance here
)

// Example with Go
import init from 'foo.wasm?instance'
import './wasm_exec.js' // it uses global variable very much :cry:

const go = new globalThis.Go()
init(go.importObject).then(({ instance }) => {
  go.run(instance)

  const result = globalThis.add(3, 2)
  console.log(result) // 5
})

declare module '*.wasm?instance' {
  // same return value with `WebAssembly.instantiate` / `WebAssembly.instantiateStreaming`
  const initWasm: (options: WebAssembly.Imports) => Promise<{ module: WebAssembly.Module, instance: WebAssembly.Instance }>
  export default initWasm
}

This feature may not be needed. Instead adding an example like below to docs may be enough.

import wasmUrl from 'foo.wasm?url'

const main = async () => {
  const res = await fetch(wasmUrl)
  const buffer = await res.arrayBuffer()
  // or `WebAssembly.instantiateStreaming()`
  const { module, instance } = await WebAssembly.instantiate(buffer)
  // use module or instance here
}

main()

[haoqunjiang]

• Currently Stage 2 in WebAssembly's process.

Seems it has already met Phase 3 requirements: WebAssembly/esm-integration#61

[sapphi-red]

Related discussions around esm integration for Node.js: nodejs/node#42309 (review)

[haoqunjiang]

We discussed this issue in yesterday's team meeting.

Our consensus was:

• Agreed the ESM integration should be dropped in the core. Let's throw an error and point the user to the community plugin.
• Considering the returned module field is rarely needed, and returning the instance only makes the code a little bit more verbose than returning the exports, we might not need that many queries. An ?init query that behaves like the current import init from './example.wasm' but exposes an instance object should suffice. That is:

import init from 'foo.wasm?init'

const imports = {}

init(imports).then((instance) =>
  // use instance here
)

To use the exports:

import init from 'foo.wasm?init'

const imports = {}

init(imports).then(({ exports }) =>
  // use exports here
)

What do you think?

[sapphi-red]

I agree module is rarely used and we should focus on instance and exports.
Your suggestion looks nice.