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 |
|
17 | WebAssembly Modules are imported asynchronous as base64 strings. Small modules [can be imported synchronously](#synchronous-modules).
|
18 |
|
19 | ## Requirements
|
20 |
|
21 | This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
|
22 |
|
23 | ## Install
|
24 |
|
25 | Using npm:
|
26 |
|
27 | ```console
|
28 | npm install @rollup/plugin-wasm --save-dev
|
29 | ```
|
30 |
|
31 | ## Usage
|
32 |
|
33 | Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
34 |
|
35 | ```js
|
36 | import wasm from '@rollup/plugin-wasm';
|
37 |
|
38 | export default {
|
39 | input: 'src/index.js',
|
40 | output: {
|
41 | dir: 'output',
|
42 | format: 'cjs'
|
43 | },
|
44 | plugins: [wasm()]
|
45 | };
|
46 | ```
|
47 |
|
48 | Then 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 |
|
52 | In addition to the properties and values specified for replacement, users may also specify the options below.
|
53 |
|
54 | ### `sync`
|
55 |
|
56 | Type: `Array[String]`
|
57 | Default: `null`
|
58 |
|
59 | Specifies 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 |
|
63 | Given the following simple C file:
|
64 |
|
65 | ```c
|
66 | int main() {
|
67 | return 42;
|
68 | }
|
69 | ```
|
70 |
|
71 | Compile the file using `emscripten`, or the online [WasmFiddle](https://wasdk.github.io/WasmFiddle//) tool. Then import and instantiate the resulting file:
|
72 |
|
73 | ```js
|
74 | import wasm from './sample.wasm';
|
75 |
|
76 | wasm({ ...imports }).then(({ instance }) => {
|
77 | console.log(instance.exports.main());
|
78 | });
|
79 | ```
|
80 |
|
81 | The 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 |
|
87 | Small modules (< 4KB) can be compiled synchronously by specifying them in the configuration.
|
88 |
|
89 | ```js
|
90 | wasm({
|
91 | sync: ['web/sample.wasm', 'web/foobar.wasm']
|
92 | });
|
93 | ```
|
94 |
|
95 | This means that the exports can be accessed immediately.
|
96 |
|
97 | ```js
|
98 | import module from './sample.wasm';
|
99 |
|
100 | const instance = sample({ ...imports });
|
101 |
|
102 | console.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 |