---
title: "WASIX with Axum"
description: "This is a sample project that shows how to use Axum with the WASIX toolchain."
url: "https://wasix.org/docs/language-guide/rust/tutorials/wasix-axum/"
markdown: "https://wasix.org/docs/language-guide/rust/tutorials/wasix-axum.md"
---

# 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:

- [Rust ](https://www.rust-lang.org/tools/install)
- [WASIX](https://wasix.org/docs/language-guide/rust/installation.md)

## Start a new project

```shell
$ 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

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

Now your `Cargo.toml` should look like this:

File: `Cargo.toml`

```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](https://wasix.org/docs/language-guide/rust/patched-repos.md).

## Writing the Application

### Basic Application Setup

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

File: `src/main.rs`

```rust
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`:

```shell
$ 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:

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

### Compiling with WASIX

Now let’s build it for WASIX:

```shell
$ 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](https://wasix.org/docs/language-guide/rust/patched-repos.md) 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

```shell
$ 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](https://wasix.org/docs/language-guide/rust/usage.md#passing-runtime-flags-with--w) for details).

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

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

Yay, it works! 🎉

> ℹ️
>
> You can also deploy your application to the edge. Checkout this [tutorial ](https://docs.wasmer.io/edge/quickstart/http-server) 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](https://github.com/wasix-org/wasix-rust-examples/tree/main/wasix-axum)

---

[Documentation index](https://wasix.org/llms.txt) · [HTML version](https://wasix.org/docs/language-guide/rust/tutorials/wasix-axum/)