Awesome
cargo run-wasm
Allows running wasm applications and examples as simply as:
cargo run-wasm --example example_name
or
cargo run-wasm --package crate_name
or
cargo run-wasm --bin bin_name
In the background it:
- Compiles the rust project to wasm
- Runs wasm-bindgen
- Generates an index.html that runs the wasm.
- Launches a tiny webserver to serve index.html + your wasm
Setup
- Setup your wasm runnable project as a crate within a cargo workspace
- Create a crate in the workspace named run-wasm with:
Cargo.toml
:
[package]
name = "run-wasm"
version = "0.1.0"
edition = "2021"
[dependencies]
cargo-run-wasm = "0.3.0"
main.rs
:
fn main() {
cargo_run_wasm::run_wasm_cli_with_css("body { margin: 0px; }");
}
- Create a
.cargo/config
file containing:
[alias]
run-wasm = "run --release --package run-wasm --"
- Thats it, you can now run the commands described earlier. You can also run
cargo run-wasm --help
to view all the possible flags.
Note: If you want to avoid restructuring your project into a proper workspace you can do so by combining your workspace and crate Cargo.toml
into a single file like winit does.
Advantages over an equivalent bash/powershell/bat script
- cross platform
- 0 external dependencies
- better UX + more robust than anything hacked together with bash/powershell/bat
- wasm-bindgen-cli version is always in sync with wasm-bindgen version because
cargo update
updates both of them at the same time thanks to being in the same workspace
cargo custom command
cargo-run-wasm is not available as a cargo custom command as that would cause:
- issues with mismatches between wasm-bindgen versions
- issues with keeping a stable interface with the wasm app
- gives the idea that the command is compatible with every project that uses wasm which is not the case.
Configuration
If you wish to set custom css, do so in the string argument to run_wasm_cli_with_css
.
However it is not possible to set custom html from cargo-run-wasm, instead any DOM elements you require should be created from within your crate or example using web-sys or another crate. The reasoning is that in the case an example requires custom HTML it will probably:
- require HTML that is unique to that example while cargo-run-wasm is only capable of global settings
- require web-sys or similar to interact with the DOM at runtime anyway
MSRV
Since this tool has a trivial implementation the MSRV is at 1.70 and will only be increased if dependencies require it. If it is ever increased it must be below the MSRV of maintained branches of important users such as wgpu and winit.
The MSRV is enforced in CI and locally via the rust-toolchain.toml
file.
Alternatives
- wasm-server-runner
- Advantages
- Integrates better with cargo
- Doesnt require any setup to live within the project
- Disadvantages
- Requires the user to run
cargo install wasm-server-runner
- wasm-bindgen versions can go out of sync causing issues like this
- Requires the user to run
- Advantages
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.