Wasmrun

Wasmrun is a powerful WebAssembly runtime that simplifies development, compilation, and deployment of WebAssembly applications.

✨ Features

• 🚀 Multi-Language Support - Build WebAssembly from Rust, Go, C/C++, AssemblyScript, and Python
• 🔌 Plugin Architecture - Extensible system with built-in and external plugins
• 🔥 Live Reload - Instant development feedback with file watching
• 🌐 Zero-Config Web Server - Built-in HTTP server with WASM and web app hosting
• 📦 Smart Project Detection - Automatically detects and configures project types
• ⚡ Zero Configuration - Works out of the box with sensible defaults and automatic project detection

🚀 Installation

From Cargo (Recommended)

cargo install wasmrun

From Source

git clone https://github.com/anistark/wasmrun.git
cd wasmrun
cargo install --path .

📖 Usage

Wasmrun supports both flag-based arguments using --path and direct positional arguments for an intuitive command line experience.

Quick Start

# Run on current directory
wasmrun

# Run a WebAssembly file directly  
wasmrun myfile.wasm

# Run a project directory
wasmrun ./my-wasm-project

# With flags
wasmrun --path ./path/to/your/file.wasm
wasmrun --path ./my-wasm-project

🔧 Commands

Development Server

Start the development server with live reload:

wasmrun run ./my-project --watch
wasmrun run ./my-project --port 3000 --language rust

Compilation

Compile a project to WebAssembly using the appropriate plugin:

wasmrun compile ./my-project
wasmrun compile ./my-project --output ./build --optimization release
wasmrun compile ./my-project --optimization size --verbose

Plugin Management

List available plugins and manage external plugins:

# List all available plugins
wasmrun plugin list

# Install external plugins
wasmrun plugin install wasmrust
wasmrun plugin install wasmgo

# Get detailed plugin information
wasmrun plugin info wasmrust
wasmrun plugin info wasmgo

Verification & Inspection

Verify a WASM file format and analyze structure:

wasmrun verify ./file.wasm
wasmrun verify ./file.wasm --detailed

wasmrun inspect ./file.wasm

Project Management

Initialize a new project:

wasmrun init my-app --template rust
wasmrun init my-app --template go --directory ./projects/

Clean build artifacts:

wasmrun clean ./my-project

Server Control

Stop any running Wasmrun server:

wasmrun stop

🏗️ Plugin Architecture

Wasmrun's modular plugin architecture enables seamless integration of different programming languages and compilation toolchains into a unified development experience. Here's a detailed guide on wasmrun plugin architecture.

Plugin Types

1. Built-in Plugins 🔧

Built-in plugins are compiled directly into Wasmrun and provide core language support:

2. External Plugins 📦

External plugins are distributed via crates.io and installed dynamically to ~/.wasmrun/:

How External Plugins Work:

• 📦 Cargo-like Installation: Similar to cargo install, plugins are downloaded and compiled to ~/.wasmrun/
• 🔗 Dynamic Loading: Plugins are loaded as shared libraries (FFI) at runtime
• 🎯 Same Interface: External plugins use identical traits as built-in plugins
• 🔧 Auto-detection: Once installed, plugins automatically handle their supported project types

Plugin Management

# Install external plugins (similar to cargo install)
wasmrun plugin install wasmrust  # Installs to ~/.wasmrun/
wasmrun plugin install wasmgo

# View all installed plugins
wasmrun plugin list

# Get detailed plugin information
wasmrun plugin info wasmrust

# Search for available plugins
wasmrun plugin search rust

# Uninstall plugins
wasmrun plugin uninstall wasmgo

Plugin Installation Process:

1. 🔍 Discovery: Searches crates.io for the plugin
2. 📦 Download: Uses cargo install to build the plugin
3. 🏠 Storage: Installs to ~/.wasmrun/plugins/{plugin_name}/
4. 📋 Registration: Updates wasmrun config with plugin capabilities
5. ⚡ Ready: Plugin automatically handles supported projects

🛠️ Language Support

Rust (via External Plugin)

# Install the Rust plugin
wasmrun plugin install wasmrust

# Run Rust projects
wasmrun ./my-rust-wasm-project

Requirements:

• Rust toolchain
• wasm32-unknown-unknown target: rustup target add wasm32-unknown-unknown
• Optional: wasm-pack for web applications

Go (via External Plugin)

# Install the Go plugin
wasmrun plugin install wasmgo

# Run Go projects
wasmrun ./my-go-wasm-project

Requirements:

• TinyGo compiler: https://tinygo.org/

C/C++ (Built-in)

# Works out of the box - no plugin installation needed
wasmrun ./my-c-project

Requirements:

• Emscripten SDK: https://emscripten.org/

AssemblyScript (Built-in)

# Works out of the box
wasmrun ./my-assemblyscript-project

Requirements:

• AssemblyScript compiler: npm install -g assemblyscript

Python (Built-in - Beta)

# Works out of the box
wasmrun ./my-python-project

Requirements:

• Python 3.11.0 (recommended to use mise)
• py2wasm: pip install py2wasm

🔍 Project Detection

Wasmrun automatically detects your project type based on:

• File extensions (.rs, .go, .c, .cpp, .py, .ts)
• Configuration files (Cargo.toml, go.mod, Makefile, package.json)
• Entry point files (main.rs, main.go, main.c, main.py, etc.)

You can override detection with the --language flag:

wasmrun --language rust ./my-project
wasmrun --language go ./my-project

🚨 Troubleshooting

Plugin Issues

"Plugin not available"

# For built-in language support:
wasmrun --language c        # C/C++ (built-in)
wasmrun --language asc      # AssemblyScript (built-in)
wasmrun --language python   # Python (built-in)

# For Rust projects, install the external plugin:
wasmrun plugin install wasmrust
# Use wasmrun plugin list to see available plugins

🚨 Open an issue and let us know about it.

"Plugin dependencies missing"

# Install missing tools for external plugins:
rustup target add wasm32-unknown-unknown  # For wasmrust plugin
go install tinygo.org/x/tinygo@latest     # For wasmgo plugin

# Check plugin dependencies:
wasmrun plugin info wasmrust  # Shows required dependencies

"Wrong plugin selected"

# Force a specific plugin
wasmrun --language rust
wasmrun --language go

External Plugin Installation

"Plugin not found during installation"

# Make sure you have the correct plugin name
wasmrun plugin install wasmrust   # For Rust support
wasmrun plugin install wasmgo     # For Go support

# Check available external plugins
wasmrun plugin list --external

Configuring py2wasm

• Make sure that you have python3.11.0 is installed and configured. We recommend using mise.

mise use python@3.11.0

• Now install py2wasm, you can use a virtual environment or not.

pip install py2wasm

• Make sure that you have named the entry file as main.py or app.py.

Common Issues

"Port is already in use"

wasmrun stop         # Stop existing server
wasmrun --port 3001  # Use different port

"No entry point found"

• Ensure your WASM has main(), _start(), or exported functions
• Use wasmrun inspect to see available exports
• Check plugin-specific entry file requirements

"wasm-bindgen module detected"

• Use the .js file instead of the .wasm file directly (wasmrust plugin)
• Run wasmrun project-dir instead of individual files

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines, including how to create and maintain plugins.

📄 License

MIT License

🙏 Credits

Wasmrun is built with love using:

• tiny_http - Lightweight HTTP server
• clap - Command line argument parsing
• notify - File system watching for live reload
• wasm-bindgen - Web integration
• Font used for logo is Pixeled by OmegaPC777.
• And the amazing Rust and WebAssembly communities ❤️

Made with ❤️ for the WebAssembly community

⭐ If you find Wasmrun useful, please consider starring the repository!