Setting Up an Axum Project

19 min read

Before you can write a single route, you need a project that compiles. This page is the “create-react-app moment” for Rust web APIs: the exact dependencies, features, project layout, and a hello-server you can run and curl.

Quick Overview

Axum is a web framework built on top of the Tokio async runtime and the Tower middleware ecosystem. Unlike Express, where npm install express gives you a server you can start immediately, an Axum app has two mandatory pieces: the framework (axum) and an async runtime (tokio). This page shows you how to wire them together, which Cargo features to turn on, how to lay out a real project, and how to get a server responding on localhost:3000.

The current stable toolchain is Rust 1.96.0 on the 2024 edition, which cargo new selects automatically. We target axum 0.8 and tokio 1.x throughout.

Note: This page covers project setup. The mechanics of routing, handlers, and axum::serve are covered in axum-basics.md; deeper routing in routing.md. For why you might choose Axum over Actix Web or Rocket, see framework-comparison.md.

TypeScript/JavaScript Example

In Node, scaffolding an Express server is a two-command affair, and the runtime (Node/V8) is already installed:

1
# Create the project
2
mkdir my-api && cd my-api
3
npm init -y
4

5
# One dependency gets you a working HTTP server
6
npm install express
7
npm install --save-dev typescript @types/express @types/node tsx

A minimal package.json and a typical layout:

1
{
2
  "name": "my-api",
3
  "version": "1.0.0",
4
  "type": "module",
5
  "scripts": {
6
    "dev": "tsx watch src/index.ts",
7
    "start": "node dist/index.js",
8
    "build": "tsc"
9
  },
10
  "dependencies": {
11
    "express": "^5.1.0"
12
  },
13
  "devDependencies": {
14
    "typescript": "^5.6.0",
15
    "@types/express": "^5.0.0",
16
    "@types/node": "^22.0.0",
17
    "tsx": "^4.19.0"
18
  }
19
}

1
my-api/
2
├── package.json
3
├── tsconfig.json
4
└── src/
5
    ├── index.ts        # entry point: creates the app, listens
6
    ├── routes.ts       # route definitions
7
    └── handlers.ts     # request handlers

1
import express from "express";
2

3
const app = express();
4

5
app.get("/", (_req, res) => {
6
  res.send("Hello, world!");
7
});
8

9
const port = 3000;
10
app.listen(port, () => {
11
  console.log(`listening on http://localhost:${port}`);
12
});

1
npm run dev
2
# listening on http://localhost:3000

Two things to notice for the comparison ahead: the runtime is implicit (Node ships an event loop), and one dependency (express) is enough. Rust differs on both counts.

Rust Equivalent

First, scaffold the project and add dependencies:

1
cargo new my-api
2
cd my-api
3
cargo add axum
4
cargo add tokio --features full

Note: cargo add has been built into Cargo since 1.62 — there is no separate cargo-edit tool to install. It edits Cargo.toml for you and resolves the newest compatible version.

The resulting Cargo.toml looks like this (versions are what resolved at the time of writing — yours may be newer):

1
[package]
2
name = "my-api"
3
version = "0.1.0"
4
edition = "2024"
5

6
[dependencies]
7
axum = "0.8.9"
8
tokio = { version = "1.52.3", features = ["full"] }

Now the entry point:

1
use axum::{routing::get, Router};
2
use tokio::net::TcpListener;
3

4
#[tokio::main]
5
async fn main() {
6
    // Build the application with a single route.
7
    let app = Router::new().route("/", get(hello));
8

9
    // Bind a TCP listener to a local address.
10
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
11
    println!("listening on http://{}", listener.local_addr().unwrap());
12

13
    // Run the server. This future never resolves until the process is stopped.
14
    axum::serve(listener, app).await.unwrap();
15
}
16

17
// A handler is just an async function returning something that implements `IntoResponse`.
18
async fn hello() -> &'static str {
19
    "Hello, world!"
20
}

Run it:

1
cargo run

Real output:

1
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.16s
2
     Running `target/debug/my-api`
3
listening on http://127.0.0.1:3000

In another terminal, curl it. This is the real response, headers included:

1
curl -i http://127.0.0.1:3000/

1
HTTP/1.1 200 OK
2
content-type: text/plain; charset=utf-8
3
content-length: 13
4
date: Mon, 01 Jun 2026 11:44:03 GMT
5

6
Hello, world!

Tip: cargo run compiles and runs in one step, so it is the closest analogue to npm run dev. For an auto-reloading dev loop like tsx watch, install cargo-watch (cargo install cargo-watch) and run cargo watch -x run.

Detailed Explanation

Let’s walk the differences a TypeScript developer will trip over.

Why two dependencies, not one?

In Node, the event loop is part of the runtime — it is always there. In Rust, the standard library does not ship an async runtime. async/await is built into the language, but the thing that actually drives those futures to completion (the executor, the I/O reactor, the timer wheel) is a library you choose. Tokio is the de-facto standard.

So the split is:

axum — the web framework: routers, extractors, responses.
tokio — the async runtime: it polls futures, manages the thread pool, and provides the async TcpListener.

This is the opposite of JavaScript, where Promises are eager (they start running the moment they are created) and the runtime is baked in. Rust futures are lazy: nothing happens until a runtime polls them. axum::serve(...) returns a future, and it is the .await — driven by the Tokio runtime — that actually runs the server. See Section 11: Async for the full mental model.

`#[tokio::main]`

1
#[tokio::main]
2
async fn main() {
3
    // ...
4
}

main cannot itself be async — the operating system calls a plain, synchronous entry point. The #[tokio::main] attribute macro rewrites your async fn main into a regular fn main that starts the Tokio runtime and blocks on your async body. Conceptually it expands to roughly:

1
fn main() {
2
    tokio::runtime::Runtime::new()
3
        .unwrap()
4
        .block_on(async {
5
            // ... your code ...
6
        });
7
}

This is not a decorator in the JavaScript/Python sense — macros operate on the syntax tree at compile time and generate new code. (See Section 14: Macros.)

`tokio::net::TcpListener` and `axum::serve`

1
let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
2
axum::serve(listener, app).await.unwrap();

In axum 0.8 you bind a Tokio TcpListener yourself and hand it to axum::serve(listener, app). This is deliberately explicit: you own the socket, which makes it trivial to bind to 0.0.0.0 in production, pick a port from the environment, or pass a pre-bound socket from systemd.

Warning: Older tutorials show axum::Server::bind(&addr).serve(app.into_make_service()). That builder was removed in axum 0.7 and does not exist in 0.8 — axum::Server no longer exists at all. Always use axum::serve(TcpListener, app). See Common Pitfalls.

The two .unwrap() calls turn a Result into a panic on error (e.g. the port is already taken). That is fine for a setup example; production code should handle these — see error-handling-web.md.

`&'static str` as a response

1
async fn hello() -> &'static str {
2
    "Hello, world!"
3
}

A handler returns any type implementing axum’s IntoResponse trait. &'static str implements it, producing a 200 OK with content-type: text/plain; charset=utf-8 — which is exactly what the curl headers above show. Returning JSON, status codes, or custom types is covered in request-response.md and json-apis.md.

Key Differences

Concern	Express (Node)	Axum (Rust)
Runtime	Built into Node	Separate crate (`tokio`), you pick it
Dependencies to start	`express` only	`axum` and `tokio`
Entry point	`app.listen(port, cb)`	`axum::serve(TcpListener, app).await`
Async model	Eager Promises, implicit loop	Lazy futures, explicit runtime via `#[tokio::main]`
Socket ownership	Hidden by `app.listen`	Explicit `TcpListener::bind(...)`
Reload-on-save	`tsx watch` / `nodemon` (built into workflow)	`cargo watch -x run` (extra tool)
Type checking	Optional layer (TypeScript)	Always on (the compiler)
Production artifact	`node dist/index.js` + `node_modules/`	A single self-contained binary

The headline difference is the explicit runtime. Once you internalize “futures are lazy and a runtime polls them,” the rest of Axum’s design (extractors, layers, IntoResponse) feels natural rather than magical.

Choosing Tokio features

tokio = { version = "1", features = ["full"] } is the simplest choice and the right default while you are learning — "full" turns on every feature (the multi-threaded runtime, networking, timers, the macros for #[tokio::main], and more).

For production you may want to trim it down. The pieces an Axum server actually needs are:

1
[dependencies]
2
tokio = { version = "1", features = ["rt-multi-thread", "net", "macros"] }

rt-multi-thread — the work-stealing multi-threaded scheduler (the default flavor of #[tokio::main]).
net — async TCP, used by TcpListener.
macros — provides #[tokio::main] and #[tokio::test].

Tip: While learning, just use features = ["full"]. Optimizing the feature set is a compile-time and binary-size concern you can revisit later; it does not change runtime behavior.

What `cargo add axum` enables

cargo add axum prints the feature flags it turned on. Here is the real output (trimmed to the feature list); a + means enabled by default, a - means available but off:

1
      Adding axum v0.8.9 to dependencies
2
             Features:
3
             + form
4
             + http1
5
             + json
6
             + matched-path
7
             + original-uri
8
             + query
9
             + tokio
10
             + tower-log
11
             + tracing
12
             - http2
13
             - macros
14
             - multipart
15
             - ws

The defaults already include JSON, query strings, and form parsing. Three optional features matter for later pages in this section:

multipart — required for file uploads (see file-uploads.md). Enable with cargo add axum --features multipart.
ws — required for WebSockets (see websockets.md). Enable with cargo add axum --features ws.
http2 — HTTP/2 support, off by default.

Recommended project layout

A one-file main.rs is fine for a toy. Real APIs split routing, handlers, and state into modules. Here is a layout that mirrors the Express src/index.ts + src/routes.ts + src/handlers.ts split and scales cleanly:

1
my-api/
2
├── Cargo.toml
3
└── src/
4
    ├── main.rs        # entry point: logging, build router, serve
5
    ├── routes.rs      # assemble the Router
6
    └── handlers.rs    # the async fn handlers

Note: In Rust, modules are declared, not auto-discovered. mod routes; in main.rs tells the compiler to load src/routes.rs. There is no equivalent of Node’s “any file under src/ is importable.” See Section 12: Modules & Packages.

src/main.rs — wires everything together and starts the server:

1
mod handlers;
2
mod routes;
3

4
use tokio::net::TcpListener;
5

6
#[tokio::main]
7
async fn main() {
8
    // Initialize structured logging. RUST_LOG controls the level (e.g. RUST_LOG=info).
9
    tracing_subscriber::fmt()
10
        .with_env_filter(
11
            tracing_subscriber::EnvFilter::try_from_default_env()
12
                .unwrap_or_else(|_| "info".into()),
13
        )
14
        .init();
15

16
    let app = routes::app();
17

18
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
19
    tracing::info!("listening on http://{}", listener.local_addr().unwrap());
20

21
    axum::serve(listener, app).await.unwrap();
22
}

src/routes.rs — the single source of truth for the API surface:

1
use axum::{routing::get, Router};
2

3
use crate::handlers;
4

5
/// Assemble the full application router. Keeping this in one place makes the
6
/// API surface easy to read and unit-test.
7
pub fn app() -> Router {
8
    Router::new()
9
        .route("/", get(handlers::root))
10
        .route("/health", get(handlers::health))
11
}

src/handlers.rs — the request handlers:

1
use axum::Json;
2
use serde::Serialize;
3

4
#[derive(Serialize)]
5
pub struct Health {
6
    status: &'static str,
7
    version: &'static str,
8
}
9

10
pub async fn root() -> &'static str {
11
    "Hello, world!"
12
}
13

14
pub async fn health() -> Json<Health> {
15
    Json(Health {
16
        status: "ok",
17
        version: env!("CARGO_PKG_VERSION"),
18
    })
19
}

This layout needs four crates. Add them with:

1
cargo add axum
2
cargo add tokio --features full
3
cargo add serde --features derive
4
cargo add serde_json
5
cargo add tracing
6
cargo add tracing-subscriber --features env-filter

tracing + tracing-subscriber give you structured logging (the Rust analogue of pino or winston); serde powers the JSON response (see Section 15: Serialization). Running it:

1
RUST_LOG=info cargo run

Real log output (the tracing-subscriber fmt formatter; it adds terminal colors when attached to a TTY):

1
2026-06-01T11:49:32.033250Z  INFO hello_server: listening on http://127.0.0.1:3000

And the /health endpoint returns real JSON:

1
curl -i http://127.0.0.1:3000/health

1
HTTP/1.1 200 OK
2
content-type: application/json
3
content-length: 33
4
date: Mon, 01 Jun 2026 11:45:03 GMT
5

6
{"status":"ok","version":"0.1.0"}

Tip: env!("CARGO_PKG_VERSION") reads the version from Cargo.toml at compile time, so /health always reports the right build version with zero maintenance.

Common Pitfalls

Pitfall 1: Forgetting `#[tokio::main]`

A plain async fn main won’t even compile, and a plain fn main can’t use .await. If you write fn main and call .await inside, you get a real error:

1
use axum::{routing::get, Router};
2
use tokio::net::TcpListener;
3

4
// does not compile (error[E0728]): missing #[tokio::main], so main is not async
5
fn main() {
6
    let app = Router::new().route("/", get(|| async { "hi" }));
7
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
8
    axum::serve(listener, app).await.unwrap();
9
}

The compiler says exactly what’s wrong:

1
error[E0728]: `await` is only allowed inside `async` functions and blocks
2
 --> src/main.rs:7:56
3
  |
4
5 | fn main() {
5
  | --------- this is not `async`
6
6 |     let app = Router::new().route("/", get(|| async { "hi" }));
7
7 |     let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
8
  |                                                        ^^^^^ only allowed inside `async` functions and blocks

Fix: add #[tokio::main] above async fn main.

Pitfall 2: Adding `tokio` without the runtime features

A very common surprise: cargo add tokio (with no --features) adds Tokio with no features enabled, so #[tokio::main] has no runtime to start:

1
[dependencies]
2
tokio = "1.52.3"   # no features — the macro can't find a runtime

1
error: The default runtime flavor is `multi_thread`, but the `rt-multi-thread` feature is disabled.
2
 --> src/main.rs:4:1
3
  |
4
4 | #[tokio::main]
5
  | ^^^^^^^^^^^^^^

Fix: add the features — cargo add tokio --features full (simplest) or at minimum ["rt-multi-thread", "net", "macros"].

Pitfall 3: Using the removed `axum::Server` API

The single most common copy-paste failure from old tutorials:

1
use axum::{routing::get, Router};
2

3
#[tokio::main]
4
async fn main() {
5
    let app = Router::new().route("/", get(|| async { "hi" }));
6
    // does not compile (error[E0433]): axum::Server was removed in 0.7
7
    axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
8
        .serve(app.into_make_service())
9
        .await
10
        .unwrap();
11
}

1
error[E0433]: failed to resolve: could not find `Server` in `axum`
2
 --> src/main.rs:7:11
3
  |
4
7 |     axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
5
  |           ^^^^^^ could not find `Server` in `axum`

Fix: bind a Tokio listener and call axum::serve:

1
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
2
axum::serve(listener, app).await.unwrap();

Pitfall 4: Expecting modules to be auto-discovered

Creating src/handlers.rs does not make it part of the crate. You must declare mod handlers; in main.rs (or another module in the tree). A forgotten mod produces an “unresolved import” / “failed to resolve” error, not silent omission. This trips up developers used to Node’s filesystem-based importing.

Pitfall 5: Reaching for `:id`-style routes

If you start adding parameterized routes, note that axum 0.8 uses {id}, not the Express-style :id. Writing :id is a 0.7-era habit that behaves differently in 0.8. This is covered in routing.md.

Best Practices

Use features = ["full"] for tokio while learning; trim to ["rt-multi-thread", "net", "macros"] once the app is real and you care about compile time.
Keep main thin. Logging setup, router assembly, and serving — that’s it. Push routes into a routes module and handlers into a handlers module from day one; it costs nothing and scales.
Expose the router from a function (pub fn app() -> Router). This makes the whole app testable without binding a port — see the test below.
Add tracing early. Structured logs from the first commit beat retrofitting println! later. Request-level logging via TraceLayer lives in middleware.md.
Bind 127.0.0.1 in development, 0.0.0.0 in production, and read the address/port from the environment for deployment. See deployment.md.
Wire in graceful shutdown before you ship, so in-flight requests finish on deploy (shown below).
Commit Cargo.lock for binaries (an API is a binary). It pins exact dependency versions for reproducible builds — the equivalent of committing package-lock.json.

Testing the router without a socket

Because app() returns a Router, you can drive it directly in tests using Tower’s oneshot, with no network involved:

1
cargo add --dev tower
2
cargo add --dev http-body-util

1
use axum::body::Body;
2
use axum::http::{Request, StatusCode};
3
use http_body_util::BodyExt;
4
use tower::ServiceExt; // brings `oneshot` into scope
5

6
#[tokio::test]
7
async fn health_returns_ok_json() {
8
    use axum::{routing::get, Router};
9
    let app = Router::new().route(
10
        "/health",
11
        get(|| async { axum::Json(serde_json::json!({ "status": "ok" })) }),
12
    );
13

14
    let response = app
15
        .oneshot(
16
            Request::builder()
17
                .uri("/health")
18
                .body(Body::empty())
19
                .unwrap(),
20
        )
21
        .await
22
        .unwrap();
23

24
    assert_eq!(response.status(), StatusCode::OK);
25

26
    let body = response.into_body().collect().await.unwrap().to_bytes();
27
    assert_eq!(&body[..], br#"{"status":"ok"}"#);
28
}

Real test output:

1
running 1 test
2
test health_returns_ok_json ... ok
3

4
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

This is far faster and more reliable than booting a real server and curl-ing it — the analogue of supertest against an Express app, but built into the type system. More on testing in Section 13: Testing.

Real-World Example

A production-flavored entry point: structured logging, configuration from the environment, binding 0.0.0.0, and graceful shutdown so a deploy doesn’t drop in-flight requests.

1
use std::net::SocketAddr;
2

3
use axum::{routing::get, Json, Router};
4
use serde::Serialize;
5
use tokio::net::TcpListener;
6
use tokio::signal;
7

8
#[derive(Serialize)]
9
struct Health {
10
    status: &'static str,
11
    version: &'static str,
12
}
13

14
async fn root() -> &'static str {
15
    "Hello, world!"
16
}
17

18
async fn health() -> Json<Health> {
19
    Json(Health {
20
        status: "ok",
21
        version: env!("CARGO_PKG_VERSION"),
22
    })
23
}
24

25
fn app() -> Router {
26
    Router::new()
27
        .route("/", get(root))
28
        .route("/health", get(health))
29
}
30

31
#[tokio::main]
32
async fn main() {
33
    // Structured logging; RUST_LOG (e.g. "info") controls verbosity.
34
    tracing_subscriber::fmt()
35
        .with_env_filter(
36
            tracing_subscriber::EnvFilter::try_from_default_env()
37
                .unwrap_or_else(|_| "info".into()),
38
        )
39
        .init();
40

41
    // Read the bind address from the environment, defaulting to all interfaces.
42
    let addr: SocketAddr = std::env::var("BIND_ADDR")
43
        .unwrap_or_else(|_| "0.0.0.0:3000".to_string())
44
        .parse()
45
        .expect("BIND_ADDR must be a valid socket address");
46

47
    let listener = TcpListener::bind(addr).await.unwrap();
48
    tracing::info!("listening on http://{}", listener.local_addr().unwrap());
49

50
    axum::serve(listener, app())
51
        .with_graceful_shutdown(shutdown_signal())
52
        .await
53
        .unwrap();
54
}
55

56
/// Resolves when the user presses Ctrl-C, letting in-flight requests finish.
57
async fn shutdown_signal() {
58
    signal::ctrl_c()
59
        .await
60
        .expect("failed to install Ctrl-C handler");
61
    tracing::info!("shutdown signal received, draining connections");
62
}

Dependencies for this example:

1
cargo add axum
2
cargo add tokio --features full
3
cargo add serde --features derive
4
cargo add tracing
5
cargo add tracing-subscriber --features env-filter

Three production details worth calling out:

with_graceful_shutdown stops accepting new connections on Ctrl-C (or SIGTERM from an orchestrator if you extend shutdown_signal) and waits for active requests to complete before the process exits.
BIND_ADDR from the environment — twelve-factor config. Default to 0.0.0.0:3000 so it works in a container without extra setup, but allow override.
No panic-on-startup behavior is hidden — bind and serve failures still surface; for handler-level errors, use a typed error response as in error-handling-web.md.

Note: Choosing the runtime flavor is a one-liner. The default is multi-threaded; for a low-concurrency sidecar you can switch to a single-threaded runtime with #[tokio::main(flavor = "current_thread")]. Both compile against the same Axum code.

Exercises

Exercise 1: Scaffold and run

Difficulty: Beginner

Objective: Build the hello-server from scratch and confirm it responds.

Instructions:

Run cargo new greeter and cd into it.
Add axum and tokio (with the full feature).
Write a server that responds with "Hello from Rust!" on GET /.
Run it with cargo run and verify with curl http://127.0.0.1:3000/.

Solution

1
cargo new greeter
2
cd greeter
3
cargo add axum
4
cargo add tokio --features full

1
use axum::{routing::get, Router};
2
use tokio::net::TcpListener;
3

4
#[tokio::main]
5
async fn main() {
6
    let app = Router::new().route("/", get(hello));
7

8
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
9
    println!("listening on http://{}", listener.local_addr().unwrap());
10

11
    axum::serve(listener, app).await.unwrap();
12
}
13

14
async fn hello() -> &'static str {
15
    "Hello from Rust!"
16
}

1
cargo run
2
# in another terminal:
3
curl http://127.0.0.1:3000/
4
# Hello from Rust!

Exercise 2: Split into modules and add `/health`

Difficulty: Intermediate

Objective: Refactor the single-file server into the recommended main.rs / routes.rs / handlers.rs layout, and add a GET /health endpoint that returns JSON.

Instructions:

Move the handlers into src/handlers.rs and the router into src/routes.rs.
Declare both modules in main.rs.
Add a health handler returning JSON like {"status":"ok"} (add serde/serde_json and use the Json type).
Verify both routes with curl.

Solution

1
cargo add axum
2
cargo add tokio --features full
3
cargo add serde --features derive
4
cargo add serde_json

1
mod handlers;
2
mod routes;
3

4
use tokio::net::TcpListener;
5

6
#[tokio::main]
7
async fn main() {
8
    let app = routes::app();
9
    let listener = TcpListener::bind("127.0.0.1:3000").await.unwrap();
10
    println!("listening on http://{}", listener.local_addr().unwrap());
11
    axum::serve(listener, app).await.unwrap();
12
}

1
use axum::{routing::get, Router};
2

3
use crate::handlers;
4

5
pub fn app() -> Router {
6
    Router::new()
7
        .route("/", get(handlers::root))
8
        .route("/health", get(handlers::health))
9
}

1
use axum::Json;
2
use serde::Serialize;
3

4
#[derive(Serialize)]
5
pub struct Health {
6
    status: &'static str,
7
}
8

9
pub async fn root() -> &'static str {
10
    "Hello, world!"
11
}
12

13
pub async fn health() -> Json<Health> {
14
    Json(Health { status: "ok" })
15
}

1
cargo run
2
curl http://127.0.0.1:3000/          # Hello, world!
3
curl http://127.0.0.1:3000/health    # {"status":"ok"}

Exercise 3: Graceful shutdown and env-configured binding

Difficulty: Advanced

Objective: Make the server production-ready: bind from an environment variable and shut down cleanly on Ctrl-C.

Instructions:

Read the bind address from a BIND_ADDR environment variable, defaulting to 0.0.0.0:3000.
Add graceful shutdown using axum::serve(...).with_graceful_shutdown(...) and tokio::signal::ctrl_c.
Run with BIND_ADDR=127.0.0.1:8080 cargo run, confirm it binds there, then press Ctrl-C and confirm it logs a shutdown message before exiting.

Solution

1
cargo add axum
2
cargo add tokio --features full

1
use std::net::SocketAddr;
2

3
use axum::{routing::get, Router};
4
use tokio::net::TcpListener;
5
use tokio::signal;
6

7
#[tokio::main]
8
async fn main() {
9
    let app = Router::new().route("/", get(|| async { "Hello, world!" }));
10

11
    let addr: SocketAddr = std::env::var("BIND_ADDR")
12
        .unwrap_or_else(|_| "0.0.0.0:3000".to_string())
13
        .parse()
14
        .expect("BIND_ADDR must be a valid socket address");
15

16
    let listener = TcpListener::bind(addr).await.unwrap();
17
    println!("listening on http://{}", listener.local_addr().unwrap());
18

19
    axum::serve(listener, app)
20
        .with_graceful_shutdown(shutdown_signal())
21
        .await
22
        .unwrap();
23
}
24

25
async fn shutdown_signal() {
26
    signal::ctrl_c()
27
        .await
28
        .expect("failed to install Ctrl-C handler");
29
    println!("shutting down gracefully");
30
}

1
BIND_ADDR=127.0.0.1:8080 cargo run
2
# listening on http://127.0.0.1:8080
3
# ... press Ctrl-C ...
4
# shutting down gracefully

Setting Up an Axum Project

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why two dependencies, not one?

`#[tokio::main]`

`tokio::net::TcpListener` and `axum::serve`

`&'static str` as a response

Key Differences

Choosing Tokio features

What `cargo add axum` enables

Recommended project layout

Common Pitfalls

Pitfall 1: Forgetting `#[tokio::main]`

Pitfall 2: Adding `tokio` without the runtime features

Pitfall 3: Using the removed `axum::Server` API

Pitfall 4: Expecting modules to be auto-discovered

Pitfall 5: Reaching for `:id`-style routes

Best Practices

Testing the router without a socket

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1: Scaffold and run

Exercise 2: Split into modules and add `/health`

Exercise 3: Graceful shutdown and env-configured binding

Setting Up an Axum Project

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why two dependencies, not one?

#[tokio::main]

tokio::net::TcpListener and axum::serve

&'static str as a response

Key Differences

Choosing Tokio features

What cargo add axum enables

Recommended project layout

Common Pitfalls

Pitfall 1: Forgetting #[tokio::main]

Pitfall 2: Adding tokio without the runtime features

Pitfall 3: Using the removed axum::Server API

Pitfall 4: Expecting modules to be auto-discovered

Pitfall 5: Reaching for :id-style routes

Best Practices

Testing the router without a socket

Real-World Example

Further Reading

Official Documentation

Related Sections

Exercises

Exercise 1: Scaffold and run

Exercise 2: Split into modules and add /health

Exercise 3: Graceful shutdown and env-configured binding

`#[tokio::main]`

`tokio::net::TcpListener` and `axum::serve`

`&'static str` as a response

What `cargo add axum` enables

Pitfall 1: Forgetting `#[tokio::main]`

Pitfall 2: Adding `tokio` without the runtime features

Pitfall 3: Using the removed `axum::Server` API

Pitfall 5: Reaching for `:id`-style routes

Exercise 2: Split into modules and add `/health`