docs(wasm): add sections about Node.js and module access (#13978)

Co-authored-by: 翠 / green <green@sapphi.red>
This commit is contained in:
tommie 2023-07-31 13:19:15 +02:00 committed by GitHub
parent e41d78e151
commit 2c73d10ed2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -500,7 +500,8 @@ Note that variables only represent file names one level deep. If `file` is `'foo
## WebAssembly
Pre-compiled `.wasm` files can be imported with `?init` - the default export will be an initialization function that returns a Promise of the wasm instance:
Pre-compiled `.wasm` files can be imported with `?init`.
The default export will be an initialization function that returns a Promise of the [`WebAssembly.Instance`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Instance):
```js
import init from './example.wasm?init'
@ -510,7 +511,7 @@ init().then((instance) => {
})
```
The init function can also take the `imports` object which is passed along to `WebAssembly.instantiate` as its second argument:
The init function can also take an importObject which is passed along to [`WebAssembly.instantiate`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate) as its second argument:
```js
init({
@ -524,13 +525,54 @@ init({
})
```
In the production build, `.wasm` files smaller than `assetInlineLimit` will be inlined as base64 strings. Otherwise, they will be copied to the dist directory as an asset and fetched on-demand.
In the production build, `.wasm` files smaller than `assetInlineLimit` will be inlined as base64 strings. Otherwise, they will be treated as a [static asset](./assets) and fetched on-demand.
::: warning
::: tip NOTE
[ES Module Integration Proposal for WebAssembly](https://github.com/WebAssembly/esm-integration) is not currently supported.
Use [`vite-plugin-wasm`](https://github.com/Menci/vite-plugin-wasm) or other community plugins to handle this.
:::
### Accessing the WebAssembly Module
If you need access to the `Module` object, e.g. to instantiate it multiple times, use an [explicit URL import](./assets#explicit-url-imports) to resolve the asset, and then perform the instantiation:
```js
import wasmUrl from 'foo.wasm?url'
const main = async () => {
const responsePromise = fetch(wasmUrl)
const { module, instance } = await WebAssembly.instantiateStreaming(
responsePromise,
)
/* ... */
}
main()
```
### Fetching the module in Node.js
In SSR, the `fetch()` happening as part of the `?init` import, may fail with `TypeError: Invalid URL`.
See the issue [Support wasm in SSR](https://github.com/vitejs/vite/issues/8882).
Here is an alternative, assuming the project base is the current directory:
```js
import wasmUrl from 'foo.wasm?url'
import { readFile } from 'node:fs/promises'
const main = async () => {
const resolvedUrl = (await import('./test/boot.test.wasm?url')).default
const buffer = await readFile('.' + resolvedUrl)
const { instance } = await WebAssembly.instantiate(buffer, {
/* ... */
})
/* ... */
}
main()
```
## Web Workers
### Import with Constructors