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