Full-stack application in Rust: Quick start

Both binaries will act as HTTP servers, and we will use Axum, one of the most popular web application frameworks for Rust, to implement that functionality.

Let's start by adding axum to the front end, which in turn adds Tokio. But since we need to enable a couple of its features, we also add it manually.

  cargo add -p frontend axum
  cargo add -p frontend -F macros,rt-multi-thread tokio

Now we modify the code in frontend/src/main.rs as shown below.

  use axum::Router;

  #[tokio::main]
  async fn main() {
      let server_addr = "localhost:3000";
      let router = Router::new();

      println!("Launching front end: http://{server_addr}");
      let listener = tokio::net::TcpListener::bind(&server_addr).await.unwrap();
      axum::serve(listener, router).await.unwrap();
  }

We can run the front-end server with cargo run -p frontend. You can connect to it from the browser using the default URL http://localhost:3000/. However, your welcome message is going to be more disappointing than warm: A 404 error. What?!? No worries, that is expected because no content is being served yet.

We can repeat, more or less, the same process for the back-end server. First, we add the dependencies.

  cargo add -p backend axum
  cargo add -p backend -F macros,rt-multi-thread tokio

And the code in backend/src/main.rs should also be almost identical.

  use axum::Router;

  #[tokio::main]
  async fn main() {
      let server_addr = "localhost:3100";
      let router = Router::new();

      println!("Launching back end: http://{server_addr}");
      let listener = tokio::net::TcpListener::bind(&server_addr).await.unwrap();
      axum::serve(listener, router).await.unwrap();
  }

You can run the back end with cargo run -p backend and try it in the browser too.

If you take a look at the Cargo.toml files of each package in the workspace, you will realize that the dependencies are identical, which is fair because we added exactly the same ones to both packages. But we would like to keep them in sync instead of having to update each one independently.

I wish cargo add let me add dependencies to the whole workspace, but that's not possible yet. So we have two options:

• We could use cargo-autoinherit, which finds dependencies used in more than one package and that can be merged in the workspace.
• Alternatively, we can do it manually by editing the three Cargo.toml files.

In this case, I will go with the latter. In the manifest of the workspace, the one in the root of the project, we add a new section and copy the two dependencies that are shared by the two packages in their manifests.

  [workspace.dependencies]
  axum = "0.8.6"
  tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread"] }

Then, in the manifests of the packages, we express dependencies using inheritance.

  [dependencies]
  axum = { workspace = true }
  tokio = { workspace = true }

We could also add the features and optional keys, should we need them. The former adds features to those declared in the workspace manifesto, specifically for the current package. The latter allows us to include them only when some feature is enabled.

Cargo has a built-in subcommand to run the clippy linter, and it is very useful to improve the quality of our code².

By default, only some of the lints are enabled. However, we can easily change the configuration of our project to make clippy a little more picky, using the pedantic lints group.

The configuration also uses inheritance, like we did with dependencies. In the project manifest, we add the following two sections. The first one avoids unsafe code, and the second one enables the pedantic lints group to produce warnings.

  [workspace.lints.rust]
  unsafe_code = "forbid"

  [workspace.lints.clippy]
  pedantic = "warn"

And we add the following section to each of the packages that wants to use the same configuration.

  [lints]
  workspace = true

Since cargo watch is now on life support, we will use bacon to monitor changes to the source and act accordingly. So we can start by installing it.

  cargo install --locked bacon

Bacon runs a job when the code changes. It knows the files it has to watch and, by default, ignores the same files that Git does. We can specify the job we want to run in the command line or use the one that is configured as the default. We can also use Control-J to select a different job from the ones that are configured.

I have produced a bacon.toml file with the default configuration using cargo --init, and I have modified that configuration to include the jobs that make more sense to me. Each job is defined in a different TOML section.

jobs.clippy

Runs clippy with the default arguments (using the configuration that we have set up above)

jobs.test and jobs.nextest

Run the tests with the default test runner or with Nextest, respectively

jobs.doc and jobs.doc-open

Produce the documentation using rustdoc and the latter opens the browser

jobs.run-frontend and jobs:run-backend

Run the front or back end package, respectively

  default_job = "clippy"
  env.CARGO_TERM_COLOR = "always"

  [jobs.clippy]
  command = ["cargo", "clippy"]
  need_stdout = false

  # This job lets you run
  # - all tests: bacon test
  # - a specific test: bacon test -- config::test_default_files
  # - the tests of a package: bacon test -- -- -p config
  [jobs.test]
  command = ["cargo", "test"]
  need_stdout = true

  [jobs.nextest]
  command = [
      "cargo", "nextest", "run",
      "--hide-progress-bar", "--failure-output", "final"
  ]
  need_stdout = true
  analyzer = "nextest"

  [jobs.doc]
  command = ["cargo", "doc", "--no-deps"]
  need_stdout = false

  # If the doc compiles, then it opens in your browser and bacon switches
  # to the previous job
  [jobs.doc-open]
  command = ["cargo", "doc", "--no-deps", "--open"]
  need_stdout = false
  on_success = "back" # so that we don't open the browser at each change

  [jobs.run-frontend]
  command = [
      "cargo", "run", "-p", "frontend",
  ]
  need_stdout = true
  allow_warnings = true
  background = false
  on_change_strategy = "kill_then_restart"

  [jobs.run-backend]
  command = [
      "cargo", "run", "-p", "backend",
  ]
  need_stdout = true
  allow_warnings = true
  background = false
  on_change_strategy = "kill_then_restart"

  [keybindings]
  c = "job:clippy" # comment this to have 'c' run clippy on only the default target
  shift-f = "job:run-frontend"
  shift-b = "job:run-backend"

We can run bacon in the terminal. If we don't provide any argument, it will run the default job, i.e., clippy for my configuration. But we can also use the name of any of the defined jobs as an argument and provide additional arguments, if needed. We can use this later on with bacon run-frontend to run the front end when its code changes.