Skip to main content

wasmrun

Compile and serve a WebAssembly project with a built-in development server.

Synopsis​

wasmrun [PROJECT] [OPTIONS]

Running is the default mode, so no subcommand is needed. wasmrun run, wasmrun dev, and wasmrun serve are accepted as explicit aliases.

Description​

The run command is wasmrun's primary development workflow. It detects your project type, compiles source code to WebAssembly using the appropriate plugin, and starts an HTTP server that serves the compiled module in a browser-based inspection UI.

When given a .wasm file directly, it skips compilation and serves immediately.

Options​

-p, --path <PATH>​

Path to a project directory or WASM file.

wasmrun --path ./my-project
wasmrun -p ./output.wasm

Default: current directory (.)

You can also use a positional argument:

wasmrun ./my-project

-P, --port <PORT>​

Port for the development server.

wasmrun --port 3000
wasmrun -P 8080
  • Default: 8420
  • Range: 1–65535

If the port is already in use, wasmrun will prompt or auto-select an available port.

-l, --language <LANGUAGE>​

Force a specific language instead of auto-detection. Useful when a project could match multiple plugins.

wasmrun --language rust
wasmrun -l go

Options: rust, go, c, asc, python

Without this flag, wasmrun auto-detects based on project files:

FileDetected Language
Cargo.tomlRust
go.modGo
Makefile (with emcc)C/C++
asconfig.jsonAssemblyScript
*.pyPython

--watch​

Enable file watching and auto-recompilation. When source files change, wasmrun recompiles and the browser refreshes automatically.

wasmrun --watch

See Live Reload for details on watched file types and behavior.

-v, --verbose​

Show detailed compilation output including compiler commands, timings, and file paths.

wasmrun --verbose

-s, --serve​

Open the browser automatically when the server starts.

wasmrun --serve

How It Works​

  1. Path resolution: resolves the input path (positional or -p flag)
  2. Type detection: if it's a .wasm file, skip to step 5. If it's a directory, continue.
  3. Plugin matching: checks installed plugins for one that handles this project type. Falls back to built-in language detection.
  4. Compilation: the matched plugin compiles source to .wasm (and optional .js glue for wasm-bindgen projects)
  5. Server startup: starts an HTTP server on the configured port
  6. Browser UI: serves an HTML page that loads the WASM module and displays its exports, memory layout, sections, and plugin info

Examples​

Serve a WASM File​

# Serve a pre-built WASM file
wasmrun ./hello.wasm

# On a custom port
wasmrun ./hello.wasm --port 3000

# Open browser automatically
wasmrun ./hello.wasm --serve

Compile and Serve a Rust Project​

# Auto-detects Rust from Cargo.toml
wasmrun ./my-rust-project

# With live reload during development
wasmrun ./my-rust-project --watch --serve

# Force language if needed
wasmrun ./my-rust-project --language rust

Compile and Serve a Go Project​

# Auto-detects Go from go.mod
wasmrun ./my-go-project

# With verbose output to see TinyGo commands
wasmrun ./my-go-project --verbose

wasm-bindgen Projects​

wasmrun automatically detects wasm-bindgen output:

# Detects _bg.wasm + .js glue files
wasmrun ./pkg/my_lib_bg.wasm

# Or point to the JS file
wasmrun ./pkg/my_lib.js

Both the WASM binary and JavaScript glue code are served together.

Development Workflow​

# Start with live reload
wasmrun ./my-project --watch --serve --port 3000

# In another terminal, make changes to source files
# Browser refreshes automatically after recompilation

CI/CD Usage​

# Compile and verify, don't start server
wasmrun compile ./my-project --optimization release
wasmrun verify ./dist/output.wasm --detailed

Browser UI​

The served page provides:

  • Module info: function count, exports, imports, memory limits, section sizes
  • Export list: all exported functions with their signatures
  • Plugin info: which plugin compiled the module, its version, and capabilities
  • Version info: wasmrun version

This data is also available via JSON endpoints:

  • GET /api/module-info: module analysis
  • GET /api/version: wasmrun version

Port Conflicts​

If port 8420 (or your specified port) is already in use:

# wasmrun detects the conflict and offers alternatives
wasmrun --port 8420
# ⚠️ Port 8420 already in use
# Using port 8421 instead

See Also​