Skip to content

Commit c23d85b

Browse files
Mencisapphi-red
andauthored
feat(wasm): direct .wasm imports (WASM ESM Integration) (#21779)
Co-authored-by: sapphi-red <[email protected]>
1 parent 5edd1d5 commit c23d85b

15 files changed

Lines changed: 314 additions & 16 deletions

File tree

‎docs/guide/features.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -663,8 +663,25 @@ These rules are enforced to prevent accidentally importing files that are not in
663663

664664
## WebAssembly
665665

666-
Pre-compiled `.wasm` files can be imported with `?init`.
667-
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):
666+
Vite supports importing pre-compiled `.wasm` files in two ways: directly as an [ES module](#esm-integration) when you only need the module's exports, or with [`?init`](#manual-initialization) when you need explicit control over instantiation.
667+
668+
### ESM Integration
669+
670+
A `.wasm` file can be imported directly. Vite reads the module's imports and exports from the binary, instantiates it, and re-exposes its exports as named ES module exports:
671+
672+
```js
673+
import { add } from './add.wasm'
674+
675+
console.log(add(1, 2)) // 3
676+
```
677+
678+
If the WebAssembly module declares imports of its own, Vite resolves them from JavaScript modules. Each import's module name is treated as an import specifier (resolved relative to the `.wasm` file) and the requested members are wired into the instance automatically.
679+
680+
This follows the [WebAssembly/ES Module Integration proposal](https://github.com/WebAssembly/esm-integration). Because a WebAssembly module is instantiated asynchronously, a directly imported `.wasm` file behaves as an async module and requires top-level `await` support.
681+
682+
### Manual Initialization
683+
684+
When you need control over when and how the module is instantiated, import it 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):
668685

669686
```js twoslash
670687
import 'vite/client'
@@ -695,14 +712,9 @@ init({
695712

696713
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.
697714

698-
::: tip NOTE
699-
[ES Module Integration Proposal for WebAssembly](https://github.com/WebAssembly/esm-integration) is not currently supported.
700-
Use [`vite-plugin-wasm`](https://github.com/Menci/vite-plugin-wasm) or other community plugins to handle this.
701-
:::
702-
703715
::: warning For SSR build, Node.js compatible runtimes are only supported
704716

705-
Due to the lack of a universal way to load a file, the internal implementation for `.wasm?init` relies on `node:fs` module. This means that this feature will only work in Node.js compatible runtimes for SSR builds.
717+
Due to the lack of a universal way to load a file, the internal implementation for both direct `.wasm` imports and `.wasm?init` relies on the `node:fs` module. This means that these features will only work in Node.js compatible runtimes for SSR builds.
706718

707719
:::
708720

‎packages/vite/client.d.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,9 @@ declare module '*.wasm?init' {
204204
export default initWasm
205205
}
206206

207+
// wasm (ESM integration)
208+
declare module '*.wasm' {}
209+
207210
// web worker
208211
declare module '*?worker' {
209212
const workerConstructor: {

‎packages/vite/src/node/plugins/index.ts‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ import type { ObjectHook } from 'rolldown'
44
import {
55
viteAliasPlugin as nativeAliasPlugin,
66
viteJsonPlugin as nativeJsonPlugin,
7-
viteWasmFallbackPlugin as nativeWasmFallbackPlugin,
87
oxcRuntimePlugin,
98
} from 'rolldown/experimental'
109
import type { PluginHookUtils, ResolvedConfig } from '../config'
@@ -135,7 +134,6 @@ export async function resolvePlugins(
135134

136135
...normalPlugins,
137136

138-
nativeWasmFallbackPlugin(),
139137
definePlugin(config),
140138
cssPostPlugin(config),
141139
buildHtmlPlugin(config),

‎packages/vite/src/node/plugins/wasm.ts‎

Lines changed: 205 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import fsp from 'node:fs/promises'
12
import MagicString from 'magic-string'
23
import { exactRegex } from 'rolldown/filter'
34
import type { RolldownMagicString } from 'rolldown'
@@ -9,6 +10,7 @@ import { assetUrlRE, fileToUrl } from './asset'
910
const wasmHelperId = '\0vite/wasm-helper.js'
1011

1112
const wasmInitRE = /(?<![?#].*)\.wasm\?init/
13+
const wasmDirectRE = /(?<![?#].*)\.wasm$/
1214

1315
const wasmInitUrlRE: RegExp = /__VITE_WASM_INIT__([\w$]+)__/g
1416

@@ -85,7 +87,7 @@ export const wasmHelperPlugin = (): Plugin => {
8587
},
8688

8789
load: {
88-
filter: { id: [exactRegex(wasmHelperId), wasmInitRE] },
90+
filter: { id: [exactRegex(wasmHelperId), wasmInitRE, wasmDirectRE] },
8991
async handler(id) {
9092
const ssr = this.environment.config.consumer === 'server'
9193

@@ -96,16 +98,33 @@ export default ${wasmHelperCode}
9698
`
9799
}
98100

99-
id = id.split('?')[0]
100-
let url = await fileToUrl(this, id, ssr)
101+
const isInit = wasmInitRE.test(id)
102+
const cleanedId = id.split('?')[0]
103+
let url = await fileToUrl(this, cleanedId, ssr)
101104
assetUrlRE.lastIndex = 0
102105
if (ssr && assetUrlRE.test(url)) {
103106
url = url.replace('__VITE_ASSET__', '__VITE_WASM_INIT__')
104107
}
105-
return `
108+
109+
if (isInit) {
110+
return `
106111
import initWasm from "${wasmHelperId}"
107112
export default opts => initWasm(opts, ${JSON.stringify(url)})
108113
`
114+
}
115+
116+
// Direct .wasm import (WASM ESM Integration)
117+
const wasmInfo = await parseWasm(cleanedId)
118+
const glueCode = generateGlueCode(wasmInfo, {
119+
initWasm: '__vite__initWasm',
120+
wasmUrl: '__vite__wasmUrl',
121+
})
122+
123+
return `
124+
import __vite__initWasm from "${wasmHelperId}"
125+
const __vite__wasmUrl = ${JSON.stringify(url)}
126+
${glueCode}
127+
`
109128
},
110129
},
111130

@@ -159,3 +178,185 @@ export default ${wasmHelperCode}
159178
}
160179
})
161180
}
181+
182+
interface WasmInfo {
183+
imports: {
184+
from: string
185+
names: string[]
186+
}[]
187+
exports: string[]
188+
}
189+
190+
async function parseWasm(wasmFilePath: string): Promise<WasmInfo> {
191+
try {
192+
const wasmBinary = await fsp.readFile(wasmFilePath)
193+
const wasmModule = await WebAssembly.compile(wasmBinary)
194+
const importMap: Record<string, string[]> = Object.create(null)
195+
for (const item of WebAssembly.Module.imports(wasmModule)) {
196+
importMap[item.module] ??= []
197+
importMap[item.module].push(item.name)
198+
}
199+
const imports = Object.entries(importMap).map(([from, names]) => ({
200+
from,
201+
names,
202+
}))
203+
204+
const exports = WebAssembly.Module.exports(wasmModule).map(
205+
(item) => item.name,
206+
)
207+
208+
return { imports, exports }
209+
} catch (e) {
210+
throw new Error(
211+
`Failed to parse WASM file "${wasmFilePath}": ${(e as Error).message}`,
212+
{ cause: e },
213+
)
214+
}
215+
}
216+
217+
function generateGlueCode(
218+
wasmInfo: WasmInfo,
219+
names: { initWasm: string; wasmUrl: string },
220+
): string {
221+
const importStatements = wasmInfo.imports.map(({ from }, i) => {
222+
return `import * as __vite__wasmImport_${i} from ${JSON.stringify(from)};`
223+
})
224+
225+
const importObject: SimpleObject = wasmInfo.imports.map(
226+
({ from, names: importNames }, i) => {
227+
return {
228+
key: JSON.stringify(from),
229+
value: importNames.map((name) => {
230+
return {
231+
key: JSON.stringify(name),
232+
value: `__vite__wasmImport_${i}[${JSON.stringify(name)}]`,
233+
}
234+
}),
235+
}
236+
},
237+
)
238+
239+
const initCode = `const __vite__wasmModule = (await ${names.initWasm}(${codegenSimpleObject(importObject)}, ${names.wasmUrl})).exports;`
240+
241+
if (wasmInfo.exports.length === 0) {
242+
return [...importStatements, initCode].join('\n')
243+
}
244+
245+
const exportStatements: string[] = []
246+
const nameMap = new Map<string, string>()
247+
for (const [index, name] of wasmInfo.exports.entries()) {
248+
if (isValidJsDeclareName(name)) {
249+
exportStatements.push(` ${name},`)
250+
} else {
251+
const placeholderName = `__vite__wasmExport_${index}`
252+
exportStatements.push(` ${JSON.stringify(name)}: ${placeholderName},`)
253+
nameMap.set(name, placeholderName)
254+
}
255+
}
256+
257+
if (nameMap.size > 0) {
258+
exportStatements.unshift(`const {`)
259+
exportStatements.push(`} = __vite__wasmModule;`)
260+
exportStatements.push(`export {`)
261+
for (const name of wasmInfo.exports) {
262+
const localName = nameMap.get(name)
263+
if (localName) {
264+
exportStatements.push(` ${localName} as ${JSON.stringify(name)},`)
265+
} else {
266+
exportStatements.push(` ${name},`)
267+
}
268+
}
269+
exportStatements.push(`};`)
270+
} else {
271+
exportStatements.unshift(`export const {`)
272+
exportStatements.push(`} = __vite__wasmModule;`)
273+
}
274+
275+
return [...importStatements, initCode, ...exportStatements].join('\n')
276+
}
277+
278+
type SimpleObject = SimpleObjectKeyValue[]
279+
280+
interface SimpleObjectKeyValue {
281+
key: string
282+
value: string | SimpleObject
283+
}
284+
285+
function codegenSimpleObject(obj: SimpleObject): string {
286+
if (obj.length === 0) return '{}'
287+
return `{ ${obj
288+
.map(({ key, value }) => {
289+
return `${key}: ${typeof value === 'string' ? value : codegenSimpleObject(value as SimpleObject)}`
290+
})
291+
.join(', ')} }`
292+
}
293+
294+
const VALID_JS_IDENTIFIER = /^[$_\p{ID_Start}][$\p{ID_Continue}]*$/u
295+
296+
const RESERVED_WORDS = new Set([
297+
'abstract',
298+
'boolean',
299+
'break',
300+
'byte',
301+
'case',
302+
'catch',
303+
'char',
304+
'class',
305+
'const',
306+
'continue',
307+
'debugger',
308+
'default',
309+
'delete',
310+
'do',
311+
'double',
312+
'else',
313+
'enum',
314+
'export',
315+
'extends',
316+
'false',
317+
'final',
318+
'finally',
319+
'float',
320+
'for',
321+
'function',
322+
'goto',
323+
'if',
324+
'implements',
325+
'import',
326+
'in',
327+
'instanceof',
328+
'int',
329+
'interface',
330+
'let',
331+
'long',
332+
'native',
333+
'new',
334+
'null',
335+
'package',
336+
'private',
337+
'protected',
338+
'public',
339+
'return',
340+
'short',
341+
'static',
342+
'super',
343+
'switch',
344+
'synchronized',
345+
'this',
346+
'throw',
347+
'throws',
348+
'transient',
349+
'true',
350+
'try',
351+
'typeof',
352+
'var',
353+
'void',
354+
'volatile',
355+
'while',
356+
'with',
357+
'yield',
358+
])
359+
360+
function isValidJsDeclareName(name: string): boolean {
361+
return !RESERVED_WORDS.has(name) && VALID_JS_IDENTIFIER.test(name)
362+
}

‎playground/ssr-wasm/__tests__/ssr-wasm.spec.ts‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ test('should work when output', async () => {
1616

1717
test.runIf(isBuild)('should not contain wasm file when inlined', async () => {
1818
const assets = await listAssets()
19-
const lightWasm = assets.find((f) => /light-.+\.wasm$/.test(f))
19+
const lightWasm = assets.find((f) => /^light-[^-]+\.wasm$/.test(f))
2020
expect(lightWasm).toBeUndefined()
2121

2222
const staticLight = await findAssetFile(/^static-light-.+\.js$/)
@@ -35,3 +35,26 @@ test.runIf(isBuild)(
3535
expect(staticHeavy).not.toContain('data:application/wasm;base64,')
3636
},
3737
)
38+
39+
test('direct wasm import', async () => {
40+
await page.goto(`${url}/direct-add`)
41+
expect(await page.textContent('.direct-add')).toMatch('3')
42+
})
43+
44+
test.runIf(isBuild)(
45+
'direct wasm import should contain and reference wasm file',
46+
async () => {
47+
const assets = listAssets()
48+
const addWasm = assets.find((f) => /add-.+\.wasm$/.test(f))
49+
expect(addWasm).toBeDefined()
50+
51+
const directAdd = findAssetFile(/^direct-add-.+\.js$/)
52+
expect(directAdd).toContain(addWasm)
53+
expect(directAdd).not.toContain('data:application/wasm;base64,')
54+
},
55+
)
56+
57+
test('direct wasm import with wasm imports', async () => {
58+
await page.goto(`${url}/direct-light`)
59+
expect(await page.textContent('.direct-light')).toMatch('42')
60+
})

‎playground/ssr-wasm/src/add.wasm‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../wasm/add.wasm

‎playground/ssr-wasm/src/app.js‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
export async function render(url) {
22
switch (url) {
33
case '/':
4-
return `<ul>${['/static-light', '/static-heavy']
4+
return `<ul>${[
5+
'/static-light',
6+
'/static-heavy',
7+
'/direct-add',
8+
'/direct-light',
9+
]
510
.map((name) => `<li><a href="${name}">${name}</a></li>`)
611
.join('')}</ul>`
712
case '/static-light':
813
return (await import('./static-light')).render()
914
case '/static-heavy':
1015
return (await import('./static-heavy')).render()
16+
case '/direct-add':
17+
return (await import('./direct-add')).render()
18+
case '/direct-light':
19+
return (await import('./direct-light')).render()
1120
}
1221
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import { add } from './add.wasm'
2+
3+
export async function render() {
4+
return `<div class="direct-add">${add(1, 2)}</div>`
5+
}
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import { exported_func } from './light-with-imports.wasm'
2+
import { getResult } from './imports.js'
3+
4+
export async function render() {
5+
exported_func()
6+
return `<div class="direct-light">${getResult()}</div>`
7+
}

‎playground/ssr-wasm/src/imports.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../wasm/imports.js

0 commit comments

Comments
 (0)