Wasix Axum

WASIX with Axum

This is a sample project that shows how to use Axum with the WASIX toolchain.

Prerequisites

⚠️

Please check that you have the latest version of wasmer runtime as this tutorial depends on version 4.1.1 or higher.

The project requires the following tools to be installed on your system:

Start a new project

$ cargo new --bin wasix-axum
     Created binary (application) `wasix-axum` package

Your wasix-axum directory structure should look like this:

wasix-axum

src
- main.rs
.gitignore
Cargo.toml

Add dependencies

$ cd wasix-axum
$ cargo add axum
$ cargo add tokio --features full

Now your Cargo.toml should look like this:

Cargo.toml

[package]
name = "wasix-axum"
version = "0.1.0"
edition = "2021"
 
[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

ℹ️

Plain versions from crates.io — no git URLs, no pins, no [patch.crates-io] section. Crates that need WASIX-specific changes (like tokio) resolve automatically through the WASIX registry.

Writing the Application

Basic Application Setup

Now, let's stub out a basic get route that returns a string using a handler function.

src/main.rs

use axum::{routing::get, Router};
 
#[tokio::main]
async fn main() {
    // Building our application with a single Route
    let app = Router::new().route("/", get(handler));
 
    // Run the server on http://127.0.0.1:3000
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();
    println!("Listening on http://127.0.0.1:3000");
    axum::serve(listener, app).await.unwrap();
}
 
async fn handler() -> &'static str {
    "Hello, Axum ❤️ WASIX!"
}

Running the Application

Run the application with cargo:

$ cargo run
   Compiling wasix-axum v0.1.0 (/wasix-axum)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.41s
     Running `target/debug/wasix-axum`
Listening on http://127.0.0.1:3000

Now in a separate terminal, you can use curl to make a request to the server:

$ curl http://127.0.0.1:3000
Hello, Axum ❤️ WASIX!%

Compiling with WASIX

Now let's build it for WASIX:

$ cargo wasix build
    Updating `.cargo/config.toml` to resolve crates through the WASIX registry
   Compiling tokio v1.47.0+wasix.1
   Compiling axum v0.8.6
   ...
   Compiling wasix-axum v0.1.0 (/wasix-axum)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 14.63s
info: Post-processing WebAssembly files
  Optimizing with wasm-opt

That's the whole setup: on the first build, cargo wasix writes the WASIX registry config into .cargo/config.toml, and the WASIX forks of low-level crates (note the tokio v1.47.0+wasix.1 above) resolve transparently — everything else comes from crates.io as usual.

ℹ️

Commit the generated .cargo/config.toml so that other checkouts and CI build through the registry too.

Running the Application on WASIX

$ cargo wasix run -W,--net

cargo wasix run builds and runs the binary with the Wasmer runtime. The -W, prefix passes comma-separated flags through to the runtime — here --net, which enables networking support (see passing runtime flags for details).

Now in a separate terminal, you can use curl to make a request to the server:

$ curl http://localhost:3000
Hello, Axum ❤️ WASIX!

Yay, it works! 🎉

ℹ️

You can also deploy your application to the edge. Checkout this tutorial (opens in a new tab) for deploying your wasix-axum server to wasmer edge.

Conclusion

In this tutorial, we learned:

How to build a simple web server using axum and compile it with wasix.
How WASIX crate forks resolve automatically through the WASIX registry.
How to run wasix based .wasm files with Wasmer.
How to pass runtime flags like --net through cargo wasix run -W,.

wasix-rust-examples/wasix-axum

Usage WASIX with Reqwest