What is @rollup/plugin-wasm?
@rollup/plugin-wasm is a Rollup plugin that allows you to import WebAssembly (Wasm) modules. This plugin helps in bundling Wasm files with your JavaScript code, making it easier to work with WebAssembly in a Rollup-based build process.
What are @rollup/plugin-wasm's main functionalities?
Importing Wasm Modules
This feature allows you to import a Wasm module directly into your JavaScript code. The imported module can then be instantiated and used within your application.
import wasmModule from './module.wasm';
wasmModule().then(instance => {
console.log(instance.exports);
});
Customizing Wasm Imports
This feature allows you to customize the way Wasm modules are imported. For example, you can specify certain modules to be imported synchronously.
import { defineConfig } from 'rollup';
import wasm from '@rollup/plugin-wasm';
export default defineConfig({
input: 'src/main.js',
output: {
dir: 'output',
format: 'esm'
},
plugins: [
wasm({
sync: ['module.wasm']
})
]
});
Other packages similar to @rollup/plugin-wasm
wasm-loader
wasm-loader is a Webpack loader for importing WebAssembly modules. It allows you to import Wasm files and use them in your JavaScript code. Compared to @rollup/plugin-wasm, wasm-loader is specifically designed for Webpack, whereas @rollup/plugin-wasm is for Rollup.
vite-plugin-wasm
vite-plugin-wasm is a Vite plugin that enables the import of WebAssembly modules. It provides similar functionality to @rollup/plugin-wasm but is tailored for Vite, a build tool that aims to provide a faster and leaner development experience.
@rollup/plugin-wasm
🍣 A Rollup which allows importing and bundling WebAssembly modules.
WebAssembly Modules are imported asynchronous as base64 strings. Small modules can be imported synchronously.
Requirements
This plugin requires an LTS Node version (v14.0.0+) and Rollup v1.20.0+.
Install
Using npm:
npm install @rollup/plugin-wasm --save-dev
Usage
Create a rollup.config.js
configuration file and import the plugin:
import { wasm } from '@rollup/plugin-wasm';
export default {
input: 'src/index.js',
output: {
dir: 'output',
format: 'cjs'
},
plugins: [wasm()]
};
Then call rollup
either via the CLI or the API.
Options
sync
Type: Array[...String]
Default: null
Specifies an array of strings that each represent a WebAssembly file to load synchronously. See Synchronous Modules for a functional example.
maxFileSize
Type: Number
Default: 14336
(14kb)
The maximum file size for inline files. If a file exceeds this limit, it will be copied to the destination folder and loaded from a separate file at runtime. If maxFileSize
is set to 0
all files will be copied.
Files specified in sync
to load synchronously are always inlined, regardless of size.
publicPath
Type: String
Default: (empty string)
A string which will be added in front of filenames when they are not inlined but are copied.
targetEnv
Type: "auto" | "browser" | "node"
Default: "auto"
Configures what code is emitted to instantiate the Wasm (both inline and separate):
"auto"
will determine the environment at runtime and invoke the correct methods accordingly"auto-inline"
always inlines the Wasm and will decode it according to the environment"browser"
omits emitting code that requires node.js builtin modules that may play havoc on downstream bundlers"node"
omits emitting code that requires fetch
WebAssembly Example
Given the following simple C file:
int main() {
return 42;
}
Compile the file using emscripten
, or the online WasmFiddle tool. Then import and instantiate the resulting file:
import sample from './sample.wasm';
sample({ ...imports }).then(({ instance }) => {
console.log(instance.exports.main());
});
The WebAssembly is inlined as a base64 encoded string. At runtime the string is decoded and a module is returned.
Note: The base64 string that represents the WebAssembly within the bundle will be ~33% larger than the original file.
Synchronous Modules
Small modules (< 4KB) can be compiled synchronously by specifying them in the configuration.
wasm({
sync: ['web/sample.wasm', 'web/foobar.wasm']
});
This means that the exports can be accessed immediately.
import sample from './sample.wasm';
const instance = sample({ ...imports });
console.log(instance.exports.main());
Meta
CONTRIBUTING
LICENSE (MIT)