rollup-plugin-rust
tl;dr -- see examples
This is a rollup plugin that loads Rust code so it can be interop with Javascript base project. Currently, the Rust code will be compiled as:
- WebAssembly module/instance
- Node.js addon/ffi
Requirements
- Node v8 or later
- Rollup v0.64 or later
-
Rust v1.28.0 with wasm32-uknown-unknown installed
rustup default 1.28.0 rustup target add wasm32-unknown-unknown
This module requires a minimum of Node v8.9.0, Rollup v0.64.0, and Rust in [nightly channel][].
Getting Started
To begin, you'll need to install rollup-plugin-rust:
npm install rollup-plugin-rust --save-dev
Then add the plugin to your rollup config. For example:
rollup.config.js
import rust from "rollup-plugin-rust";
export default [
{
input: "src/main.js",
output: {
file: "dist.index.js",
format: "esm"
},
plugins: [rust()]
}
];
quick usage
lib.rs
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
index.js
import wasm from "lib.rs";
export async function increment(a) {
const { instance } = await wasm;
return instance.exports.add(1, a);
}
And run rollup via your preferred method.
Options
export
How wasm code would be exported. This options is identical with option export in webassembly-loader. (see examples)
// in your rollup.config.js
{
plugins: [rust({ export: "instance" })];
}
target
- Type:
String - Default:
wasm32-unknown-unknown - Expected value: see supported platform
The Rust target to use. Currently it only support wasm related target
// in your rollup.config.js
{
plugins: [rust({ target: "wasm32-unknown-emscripten" })];
}
release
- Type:
Boolean - Default:
true
Whether to compile the Rust code in debug or release mode.
// in your rollup.config.js
{
plugins: [rust({ release: false })]; // preserve debug symbol
}
include
- Type:
Array<string>orstring - Default:
['**/*.rs']
A single file, or array of files, to include when compiling.
// in your rollup.config.js
{
plugins: [
rust({
include: ["src/**/*.rs", "test/**/*.rs"]
})
];
}
exclude
- Type:
Array<string>orstring - Default:
['node_modules/**', 'target/**']
A single file, or array of files, to exclude when linting.
// in your rollup.config.js
{
plugins: [
rust({
exclude: ["**/node_modules/**", "**/target/**", "**/__caches__/**"]
})
];
}
Examples
See the test cases and example projects in fixtures and examples for more insight.
TL;DR
Given this Rust code
lib.rs
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
Cargo.toml
[package]
name = "adder"
version = "0.1.0"
authors = ["Full Name <[email protected]>"]
[lib]
crate-type = ["cdylib"]
path = "lib.rs"
With options
{export: 'buffer'}
import wasmCode from "./lib.rs";
WebAssembly.compile(wasmCode).then(module => {
const instance = new WebAssembly.Instance(module);
console(instance.exports.add(1, 2)); // 3
});
{export: 'module'}
import wasmModule from "./lib.rs";
const instance = new WebAssembly.Instance(wasmModule);
console(instance.exports.add(1, 2)); // 3
{export: 'instance'}
import wasm from "./lib.rs";
console(wasm.exports.add(1, 2)); // 3
{export: 'async'}
extern {
fn hook(c: i32);
}
#[no_mangle]
pub fn add(a: i32, b: i32) -> i32 {
hook(a + b)
}
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(({ instance, module }) => {
console(instance.exports.add(1, 2)); // 3
// create different instance, extra will be called in different environment
const differentInstance = new WebAssembly.Instance(module, {
env: {
hook: result => result * 2
}
});
console(differentInstance.exports.add(1, 2)); // 6
});
{export: 'async-instance'}
import wasmInstantiate from "./lib.rs";
wasmInstantiate(importObject | undefined).then(instance => {
console(instance.exports.add(1, 2)); // 3
});
{export: 'async-module'}
import wasmInstantiate from "./lib.rs";
wasmCompile(importObject | undefined).then(module => {
const differentInstance = new WebAssembly.Instance(module);
console(differentInstance.exports.add(1, 2)); // 3
});
You may also want to look at
Who use this?
- example-stencil-rust
- [add yours
😉 ]
Contributing
- CONTRIBUTING.md for how you can make contribution
- HACKING.md for technical details
1 Nov 21, 2021
3 Jul 12, 2023
38 Dec 24, 2022
4 Jun 8, 2023
10 Dec 8, 2022
7 Jan 1, 2023
11 Oct 20, 2022
18 Apr 1, 2023
5 Aug 2, 2023
27 Feb 19, 2022
86 Dec 27, 2022
65 Dec 31, 2022
61 Jan 1, 2023
19 Jun 12, 2023
7 Jan 18, 2023
6 Apr 7, 2024
128 Jan 1, 2023
15 Nov 14, 2022
2 May 6, 2022