UNPKG

2.96 kBMarkdownView Raw
1[cover]: https://codecov.io/gh/rollup/plugins/replace/branch/master/graph/badge.svg
2[cover-url]: https://codecov.io/gh/rollup/plugins
3[size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-wasm
4[size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-wasm
5[tests]: https://img.shields.io/circleci/project/github/rollup/plugins.svg
6[tests-url]: https://circleci.com/gh/rollup/plugins
7
8[![tests][tests]][tests-url]
9[![cover][cover]][cover-url]
10[![size][size]][size-url]
11[![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)
12
13# @rollup/plugin-wasm
14
15🍣 A Rollup which allows importing and bundling [WebAssembly modules](http://webassembly.org).
16
17WebAssembly Modules are imported asynchronous as base64 strings. Small modules [can be imported synchronously](#synchronous-modules).
18
19## Requirements
20
21This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
22
23## Install
24
25Using npm:
26
27```console
28npm install @rollup/plugin-wasm --save-dev
29```
30
31## Usage
32
33Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
34
35```js
36import wasm from '@rollup/plugin-wasm';
37
38export default {
39 input: 'src/index.js',
40 output: {
41 dir: 'output',
42 format: 'cjs'
43 },
44 plugins: [wasm()]
45};
46```
47
48Then call `rollup` either via the [CLI](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api).
49
50## Options
51
52In addition to the properties and values specified for replacement, users may also specify the options below.
53
54### `sync`
55
56Type: `Array[String]`
57Default: `null`
58
59Specifies an array of strings that each represent a WebAssembly file to load synchronously. See [Synchronous Modules](#synchronous-modules) for a functional example.
60
61## WebAssembly Example
62
63Given the following simple C file:
64
65```c
66int main() {
67 return 42;
68}
69```
70
71Compile the file using `emscripten`, or the online [WasmFiddle](https://wasdk.github.io/WasmFiddle//) tool. Then import and instantiate the resulting file:
72
73```js
74import wasm from './sample.wasm';
75
76wasm({ ...imports }).then(({ instance }) => {
77 console.log(instance.exports.main());
78});
79```
80
81The WebAssembly is inlined as a base64 encoded string. At runtime the string is decoded and a module is returned.
82
83_Note: The base64 string that represents the WebAssembly within the bundle will be ~33% larger than the original file._
84
85### Synchronous Modules
86
87Small modules (< 4KB) can be compiled synchronously by specifying them in the configuration.
88
89```js
90wasm({
91 sync: ['web/sample.wasm', 'web/foobar.wasm']
92});
93```
94
95This means that the exports can be accessed immediately.
96
97```js
98import module from './sample.wasm';
99
100const instance = sample({ ...imports });
101
102console.log(instance.exports.main());
103```
104
105## Meta
106
107[CONTRIBUTING](./.github/CONTRIBUTING.md)
108
109[LICENSE (MIT)](./LICENSE)
110
\No newline at end of file