Skip to content

Commit

Permalink
docs(wasm): add sections about Node.js and module access (#13978)
Browse files Browse the repository at this point in the history
Co-authored-by: 翠 / green <green@sapphi.red>
  • Loading branch information
tommie and sapphi-red authored Jul 31, 2023
1 parent e41d78e commit 2c73d10
Showing 1 changed file with 46 additions and 4 deletions.
50 changes: 46 additions & 4 deletions docs/guide/features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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({
Expand All @@ -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
Expand Down

0 comments on commit 2c73d10

Please sign in to comment.