wasmrust 0.3.0

Rust WebAssembly plugin for Wasmrun - compile Rust projects to WebAssembly with wasm-bindgen support
Documentation

๐Ÿฆ€ WasmRust

Crates.io Version Crates.io Downloads Crates.io Downloads (latest version) Open Source Contributors maintenance-status

Rust Rust to WebAssembly compiler plugin for Wasmrun. Compile and run Rust projects to WebAssembly to run easily on any wasm based ecosystem.

๐Ÿ“ฆ Installation

Primary Installation (Wasmrun Plugin)

# Install wasmrun first
cargo install wasmrun

# Install the wasmrust plugin  
wasmrun plugin install wasmrust

# Verify installation
wasmrun plugin info wasmrust

Standalone Installation (Development/Testing)

# Install as standalone CLI tool
cargo install wasmrust --features cli

# Verify standalone installation
wasmrust info

Library Integration

[dependencies]
wasmrust = "0.2.1"

# For wasmrun plugin development
wasmrust = { version = "0.2.1", features = ["wasmrun-integration"] }

# For CLI usage
wasmrust = { version = "0.2.1", features = ["cli"] }

๐Ÿ› ๏ธ Usage

Primary Usage (via Wasmrun) - Recommended

Wasmrun automatically detects Rust projects and uses the wasmrust plugin:

# Automatic project detection and compilation
wasmrun ./my-rust-project

# Web application with live reload  
wasmrun ./my-yew-app --watch

# Compile with specific optimization
wasmrun compile ./my-project --optimization size

# Force Rust plugin usage (mixed projects)
wasmrun ./mixed-project --language rust

# Plugin management
wasmrun plugin info wasmrust
wasmrun plugin list

Standalone Usage (Development/Testing)

For development, testing, or environments without wasmrun:

# Compile project to WebAssembly
wasmrust compile --project ./my-project --output ./dist

# Run project for execution (AOT compilation)
wasmrust run ./my-project

# Inspect project structure and dependencies
wasmrust inspect ./my-project

# Check if project is supported
wasmrust can-handle ./my-project

# Check system dependencies
wasmrust check-deps

# Clean build artifacts
wasmrust clean ./my-project

# Show supported frameworks
wasmrust frameworks

Library Usage

use wasmrust::{WasmRustPlugin, CompileConfig, OptimizationLevel, TargetType};

let plugin = WasmRustPlugin::new();

// Check if project is supported
if plugin.can_handle("./my-project") {
    let config = CompileConfig {
        project_path: "./my-project".to_string(),
        output_dir: "./dist".to_string(),
        optimization: OptimizationLevel::Release,
        target_type: TargetType::WebApp,
        verbose: true,
    };
    
    match plugin.compile(&config) {
        Ok(result) => {
            println!("WASM: {}", result.wasm_path);
            if let Some(js_path) = result.js_path {
                println!("JS: {}", js_path);
            }
        }
        Err(e) => eprintln!("Compilation failed: {}", e),
    }
}

๐ŸŽฏ Supported Project Types & Frameworks

Project Types (Auto-detected)

Type Description Output Build Tool
Standard WASM Basic Rust โ†’ WebAssembly .wasm file cargo
wasm-bindgen JavaScript integration .wasm + .js wasm-pack
Web Application Full-stack web apps Complete bundle trunk / wasm-pack

Supported Web Frameworks

Framework Auto-Detection Build Strategy Status
Yew yew dependency trunk โ†’ wasm-pack โœ… Full Support
Leptos leptos dependency trunk โ†’ wasm-pack โœ… Full Support
Dioxus dioxus dependency wasm-pack โœ… Full Support
Sycamore sycamore dependency wasm-pack โœ… Full Support
Trunk Trunk.toml present trunk โœ… Full Support

Framework Examples

Standard Rust WASM

[package]
name = "my-wasm-lib"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

wasm-bindgen Project

[package]
name = "my-bindgen-project"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2"
web-sys = "0.3"

Yew Web Application

[package]
name = "my-yew-app"
version = "0.1.0"
edition = "2021"

[dependencies]
yew = "0.21"
wasm-bindgen = "0.2"

๐Ÿ”ง Build Strategies & Optimization

Build Strategy Selection

WasmRust intelligently selects the optimal build strategy:

Project Analysis
      โ†“
Framework Detection (Yew, Leptos, etc.)
      โ†“
Build Tool Selection:
  โ€ข Standard WASM โ†’ cargo build
  โ€ข wasm-bindgen โ†’ wasm-pack  
  โ€ข Web Apps โ†’ trunk (preferred) โ†’ wasm-pack (fallback)
      โ†“
Optimization Application
      โ†“
Output Generation

Optimization Levels

Level Compilation Time File Size Performance Use Case
debug Fast โšก Large ๐Ÿ“ฆ Basic โญ Development, debugging
release Moderate โฑ๏ธ Medium ๐Ÿ“ฆ Good โญโญโญ Production builds
size Slow ๐ŸŒ Minimal ๐Ÿ“ฆ Good โญโญโญ Bandwidth-constrained

Advanced Optimization

# Cargo.toml optimization for smallest WASM
[profile.release]
opt-level = "s"          # Optimize for size
lto = true               # Link-time optimization
codegen-units = 1        # Slower compile, smaller binary
panic = "abort"          # Smaller binary
strip = "symbols"        # Remove debug symbols

[profile.release.package."*"]
opt-level = "s"

# Web-specific optimizations
[dependencies]
console_error_panic_hook = "0.1"
wee_alloc = "0.4"

๐Ÿ” Project Analysis & Dependencies

Inspect Your Project

wasmrust inspect ./my-project

Example Output:

๐Ÿ” Analyzing Rust project...

๐Ÿ“Š Project Analysis
โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
๐Ÿ“ Name: my-yew-app
๐Ÿท๏ธ  Version: 0.1.0  
๐ŸŽฏ Type: Web Application
๐Ÿ”ง Build Strategy: trunk + wasm-pack
๐ŸŒ Frameworks: yew, trunk

๐Ÿ“‹ Dependencies
โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•
Required:
   โœ… cargo - Rust build tool
   โœ… rustc - Rust compiler  
   โœ… wasm32-unknown-unknown - WebAssembly compilation target
   โœ… trunk - Required for web application builds

Optional:
   โœ… rustup - Rust toolchain manager
   โš ๏ธ  wasm-opt - WebAssembly optimizer

๐ŸŽ‰ Project is ready to build!

System Dependencies

Required Tools

  • Rust Toolchain: rustup, cargo, rustc
  • WASM Target: wasm32-unknown-unknown

Optional Tools (Auto-detected)

  • wasm-pack: For wasm-bindgen projects
  • trunk: For web applications
  • wasm-opt: For additional optimization

Quick Installation

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add WebAssembly target
rustup target add wasm32-unknown-unknown

# Install additional tools
cargo install wasm-pack trunk wasm-opt

# Verify installation
wasmrust check-deps

๐Ÿ”„ Live Development & Watch Mode

File Watching (via Wasmrun)

WasmRust automatically monitors:

  • src/**/*.rs - Source files
  • Cargo.toml - Dependencies and configuration
  • Trunk.toml - Trunk configuration
  • assets/, static/, public/ - Static assets
  • style.css, index.html - Web assets

Development Workflow

# Start development server with live reload
wasmrun ./my-project --watch

โš™๏ธ Configuration

Project Configuration

Create wasmrun.toml in your project root:

[project]
language = "rust"

[build]
optimization = "release"
target_type = "webapp"
output_dir = "./dist"

[rust]
build_strategy = "trunk"        # cargo, wasm-pack, trunk
wasm_pack_target = "web"        # web, bundler, nodejs
enable_optimization = true
custom_flags = ["--features", "web"]

Global Plugin Configuration

Configure in ~/.wasmrun/config.toml:

[external_plugins.wasmrust]
enabled = true
auto_update = true
install_path = "/home/user/.wasmrun/plugins/wasmrust"

[external_plugins.wasmrust.defaults]
optimization = "size"
verbose = false
build_strategy = "auto"

Environment Variables

# Enable verbose compilation
export WASMRUST_VERBOSE=1

# Custom optimization flags
export RUSTFLAGS="-C target-feature=+simd128"

# Force build strategy
export WASMRUST_BUILD_STRATEGY=trunk

๐Ÿ”ง Plugin Architecture & Integration

Wasmrun Plugin Interface

WasmRust implements the full Wasmrun plugin architecture:

// Plugin trait implementation
impl Plugin for WasmrustPlugin {
    fn info(&self) -> &PluginInfo;
    fn can_handle_project(&self, project_path: &str) -> bool;
    fn get_builder(&self) -> Box<dyn WasmBuilder>;
}

// Builder trait implementation  
impl WasmBuilder for WasmrustBuilder {
    fn build(&self, config: &BuildConfig) -> CompilationResult<BuildResult>;
    fn check_dependencies(&self) -> Vec<String>;
    fn validate_project(&self, project_path: &str) -> CompilationResult<()>;
    fn clean(&self, project_path: &str) -> Result<()>;
    // ... additional methods
}

Dynamic Loading Support

WasmRust supports both library integration and dynamic loading:

// C interface for dynamic loading
extern "C" {
    fn wasmrun_plugin_create() -> *mut c_void;
    fn wasmrust_can_handle_project(builder: *const c_void, path: *const c_char) -> bool;
    fn wasmrust_build(builder: *const c_void, config: *const BuildConfigC) -> *mut BuildResultC;
    // ... additional C functions
}

Plugin Registration

// Rust integration
use wasmrust::create_plugin;

let plugin = create_plugin(); // Returns Box<dyn Plugin>

// C integration  
extern "C" fn wasmrun_plugin_create() -> *mut c_void;

๐Ÿ” Troubleshooting

Common Issues

"Plugin not found"

# Verify plugin installation
wasmrun plugin list
wasmrun plugin info wasmrust

# Reinstall if needed
wasmrun plugin install wasmrust

"wasm32-unknown-unknown target not found"

rustup target add wasm32-unknown-unknown

"wasm-pack not found" (for wasm-bindgen projects)

cargo install wasm-pack

"trunk not found" (for web applications)

cargo install trunk

"Compilation timeout"

# Increase timeout for large projects
wasmrun compile ./large-project --timeout 300

# Use incremental compilation
export CARGO_INCREMENTAL=1

๐Ÿงช Testing & Development

Running Tests

# Run all tests
cargo test

# Test wasmrun integration
cargo test --features wasmrun-integration

# Test CLI functionality
cargo test --features cli

# Integration tests (requires Rust toolchain)
cargo test test_actual_compilation -- --ignored

Development Setup

TBD

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes with tests
  4. Run the test suite: cargo test --all-features
  5. Update documentation if needed
  6. Submit a pull request

Adding Framework Support

  1. Update detection logic in detect_project_type_and_frameworks()
  2. Add build strategy in determine_build_strategy()
  3. Implement compilation in framework-specific methods
  4. Add tests and update documentation
  5. Update README with framework details

๐Ÿ“Š Benchmarks & Performance

Compilation Speed

Project Type Debug Release Size
Simple WASM ~5s ~15s ~25s
wasm-bindgen ~10s ~30s ~45s
Yew App ~15s ~45s ~60s

Output Size Comparison

Optimization Simple WASM wasm-bindgen Yew App
debug ~500KB ~800KB ~1.2MB
release ~200KB ~400KB ~600KB
size ~100KB ~250KB ~400KB

Benchmarks on Apple M1, Rust 1.70, realistic projects

๐Ÿ”— Related Projects & Ecosystem

Core Dependencies

Web Frameworks

  • Yew - Modern Rust web framework
  • Leptos - Full-stack Rust framework
  • Dioxus - Cross-platform GUI library
  • Sycamore - Reactive web library

Related Tools

  • Wasmrun - Universal WebAssembly runtime
  • WasmGo - Go WebAssembly plugin
  • binaryen - WebAssembly optimizer

๐Ÿ“„ License

MIT License - see the LICENSE file for details.

๐Ÿค Contributing & Community

Getting Help

Contributing

We welcome contributions! See CONTRIBUTING.md for:

  • Code contribution guidelines
  • Development setup instructions
  • Testing requirements
  • Documentation standards

Made with โค๏ธ for the Rust and WebAssembly communities

โญ If you find WasmRust useful, please consider starring the repository!