{"id":446562,"date":"2024-02-28T13:13:56","date_gmt":"2024-02-28T12:13:56","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=rust&p=446562"},"modified":"2024-02-28T13:14:01","modified_gmt":"2024-02-28T12:14:01","slug":"how-to-write-your-first-rust-web-app-with-rocket-and-rustrover","status":"publish","type":"rust","link":"https:\/\/blog.jetbrains.com\/en\/rust\/2024\/02\/28\/how-to-write-your-first-rust-web-app-with-rocket-and-rustrover","title":{"rendered":"How to Write Your First Rust Web App with Rocket and RustRover"},"content":{"rendered":"\n

If you\u2019re like me and you\u2019re just starting your Rust journey, you likely have some or most of your experience from another ecosystem. That\u2019s great, but you\u2019re hearing a lot about this new technology stack called Rust and are wondering where to start. Have no fear. We\u2019ve got the tutorial just for you. In this post, we\u2019ll build a simple HTML web application running on a Rust backend using the Rocket library.<\/p>\n\n\n\n

If you haven\u2019t already, now is a great time to download RustRover<\/a>, our latest IDE explicitly designed for the Rust community. You\u2019ll also want to install Rust using RustRover<\/a> or by using the community getting started guide<\/a>.<\/p>\n\n\n\n

By the end of this tutorial, we\u2019ll have a web application hosting static files, an application with multiple endpoints, server-side template rendering, flash messaging, and request\/response flows. First, let\u2019s look at the library we\u2019ll be using, then dive into the specifics of building our sample application.<\/p>\n\n\n\n

What is Rocket?<\/h2>\n\n\n\n

Rocket is a web framework built for Rust<\/a> that makes writing fast, type-safe, secure web applications simple. Like many modern web frameworks, Rocket expresses its application-building philosophy by adding endpoints accessible at unique paths. Rocket has out-of-the-box support for routing, data handling, validation, responders, cookies, web sockets, and database access. It is a fully-featured framework built on top of what makes Rust unique: type safety and macros.<\/p>\n\n\n\n

Now that you have a high-level understanding of Rocket, let\u2019s start building our application.<\/p>\n\n\n\n

A New Rocket Project<\/h2>\n\n\n\n

After starting RustRover, you\u2019ll want to create a new project from the New Project <\/strong>dialog.<\/p>\n\n\n\n

You can call your project anything you\u2019d like, but I\u2019ll call mine \u201crocketapp\u201d<\/code> for this tutorial. Be sure to select the \u201cBinary (application)\u201d<\/strong> option and then click the Create<\/strong> button.<\/p>\n\n\n\n

\"New<\/figure>\n\n\n\n

Let\u2019s set up the project\u2019s dependencies. In your Cargo.toml<\/code> file, add the rocket<\/code> and rocket_dyn_templates<\/code> dependencies. RustRover will automatically download and update your crates whenever you add new dependencies, which is a fantastic feature.<\/strong><\/p>\n\n\n\n

[package]\nname = \"rocketapp\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[dependencies]\nrocket = \"0.5.0\"\nrocket_dyn_templates = { version = \"0.1.0\", features = [\"handlebars\", \"tera\"] }<\/pre>\n\n\n\n
Next, in your main.rs<\/code> file, paste the following code. Here, we\u2019ll add a new endpoint that responds with a String<\/code> value. Take note of the #[get(\u201c\/\u201d)]<\/code> attribute, which tells the Rust compiler about additional metadata for our newly created endpoint. In this case, a new endpoint responds to a user HTTP GET<\/code> request at the \/<\/code> path.<\/p>\n\n\n\n
use rocket::{get, launch, routes};\n\n#[launch]\nfn rocket() -> _ {\n    rocket::build()\n        .mount(\"\/\", routes![root])\n}\n\n#[get(\"\/\")]\nasync fn root() -> String {\n    \"Hello, World\".to_string()\n}\n<\/pre>\n\n\n\n
You should be able to run your application now using the Run Toolbar<\/strong> to initiate a new instance of your web application.<\/p>\n\n\n\n
\"Running<\/figure>\n\n\n\n
Congratulations! You have successfully built your first Rust-powered application. Next, let\u2019s modify our application to include static file hosting, template rendering, and practice some response flow.<\/p>\n\n\n\n
Level-up The Rocket Application<\/h2>\n\n\n\n
As a first step, let\u2019s add two new directories to the project’s root: templates<\/code> and public<\/code>. The templates<\/code> directory will hold our view templates, while the public<\/code> directory will hold static artifacts such as CSS, images, or JavaScript files.<\/p>\n\n\n\n
I\u2019ve copied the Pico CSS library<\/a> to a css<\/code> folder, giving me some basic styling, which I\u2019ll use later in my HTML templates.<\/p>\n\n\n\n
\"The<\/figure>\n\n\n\n
Now, let\u2019s update our application to render a new Handlebars <\/strong>template. Add a new root.html.hbs<\/code> file to the templates<\/code> directory with the following HTML.<\/p>\n\n\n\n
<html lang=\"\">\n<head>\n    <meta charset=\"UTF-8\">\n    <meta name=\"viewport\"\n          content=\"width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0\">\n    <meta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\">\n    <link href=\"\/public\/css\/pico.min.css\" rel=\"stylesheet\">\n    <title>Hello Rust<\/title>\n<\/head>\n<body>\n<main class=\"container\">\n    <h1>{{message}}<\/h1>\n<\/main>\n<\/body>\n<\/html>\n<\/pre>\n\n\n\n
You can install the Handlebars plug-in from the JetBrains Marketplace<\/a> to make working with this syntax much more enjoyable. We need to modify our main.rs <\/code>file again, but this time, we\u2019ll register the template system and map our static file directory to a path.<\/p>\n\n\n\n
use rocket::{get, launch, routes};\nuse rocket::fs::{FileServer, Options, relative};\nuse rocket_dyn_templates::{context, Template};\n\n#[launch]\nfn rocket() -> _ {\n    rocket::build()\n        \/\/ add templating system\n        .attach(Template::fairing())\n        \/\/ serve content from disk\n        .mount(\"\/public\", FileServer::new(relative!(\"\/public\"), Options::Missing | Options::NormalizeDirs))\n        \/\/ register routes\n        .mount(\"\/\", routes![root])\n}\n\n#[get(\"\/\")]\nasync fn root() -> Template {\n    Template::render(\"root\", context! { message: \"Hello, Rust\"})\n}\n<\/pre>\n\n\n\n
Now we\u2019re getting somewhere. You\u2019ll notice the use of the symbols amongst the code, mostly #<\/code> and !<\/code>. The usage is known as \u201cmacros\u201d<\/a> and is a fundamental part of the Rust language. Macros allow you to write declarative code while giving the Rust compiler hints as to what code to generate at compile time to make your application work. While other languages may lean on runtime discovery, Rust can determine how parts interact with each other at compile time, thus reducing wasted CPU cycles and unnecessary memory allocations.<\/p>\n\n\n\n
Let\u2019s start handling user data from HTML forms.<\/p>\n\n\n\n
Data Handling in Rocket<\/h2>\n\n\n\n
We\u2019ve already established that Rust is about type and memory safety, so it should be no surprise that memory structures are an essential part of the language. You can think of structures as places in memory where our data lives, preferably in the fastest parts. Rocket lets us use a struct<\/code> to represent form requests coming from HTML. Add the following data type in a new models.rs<\/code> file in your src<\/code> directory.<\/p>\n\n\n\n
use rocket::{FromForm};\n\n#[derive(FromForm, Debug)]\npub struct Person {\n    #[field(validate=len(1..))]\n    pub(crate) first_name: String,\n    #[field(validate=len(1..))]\n    pub(crate) last_name: String,\n}\n<\/pre>\n\n\n\n
A few things are happening in this small snippet of code.<\/p>\n\n\n\n
    \n
  1. We are using the field<\/code> macro and derive<\/code> implementation for two different traits, FromForm<\/code> and Debug<\/code><\/li>\n\n\n\n
  2. The keyword pub<\/code> denotes that the struct<\/code> and its fields are publicly accessible.<\/li>\n\n\n\n
  3. Each field uses built-in Rocket validators for length; many more are available.<\/li>\n<\/ol>\n\n\n\n
    Let\u2019s update our root<\/code> template to handle submitting a form using this Person<\/code> structure.<\/p>\n\n\n\n
    <!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <meta name=\"color-scheme\" content=\"light dark\"\/>\n    <link rel=\"stylesheet\" href=\"\/public\/css\/pico.min.css\">\n    <title>Hello world!<\/title>\n<\/head>\n<body>\n<main class=\"container\">\n    <h1>Hello Rust!<\/h1>\n\n    {{#if errors }}\n        <article>\n            <header>🥺Oh No!<\/header>\n            <p>There are some invalid fields in the form<\/p>\n            <ul>\n                {{#each errors}}\n                    <li>{{this}}<\/li>\n                {{\/each}}\n            <\/ul>\n        <\/article>\n    {{\/if}}\n\n    <form method=\"POST\" enctype=\"multipart\/form-data\" action=\"\/\">\n        <input type=\"text\"\n               name=\"first_name\"\n               placeholder=\"First Name\"\n               aria-label=\"First Name\"\n               value=\"{{ first_name }}\"\n               aria-invalid=\"{{ first_name_error}}\"\n        \/>\n\n        <input type=\"text\" name=\"last_name\"\n               placeholder=\"Last Name\"\n               aria-label=\"Last Name\"\n               value=\"{{ last_name }}\"\n               aria-invalid=\"{{ last_name_error}}\"\n        \/>\n        \n        <button type=\"submit\">Say Hello<\/button>\n    <\/form>\n<\/main>\n<\/body>\n<\/html>\n<\/pre>\n\n\n\n
    You\u2019ll likely notice a few Handlebars placeholders, which we will use in subsequent endpoints, so hold tight.<\/p>\n\n\n\n
    Before returning to Rust, add one more template for our success page. I\u2019ve called it hello.html.hbs<\/code> in the templates<\/code> directory.<\/p>\n\n\n\n
    <!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <meta name=\"color-scheme\" content=\"light dark\" \/>\n    <link rel=\"stylesheet\" href=\"\/public\/css\/pico.min.css\">\n    <title>Hello {{ name }}!<\/title>\n<\/head>\n<body>\n<main class=\"container\">\n    <dialog open>\n        <article>\n            <header>\n                <a href=\"\/\" aria-label=\"Close\" rel=\"prev\"><\/a>\n                <p>\n                    <strong>🗓️ {{ message }}!<\/strong>\n                <\/p>\n            <\/header>\n            <p>\n                Hello {{ name }}\n            <\/p>\n        <\/article>\n    <\/dialog>\n<\/main>\n<\/body>\n<\/html>\n<\/pre>\n\n\n\n
    We need to write two endpoints now, one to handle the user request and the other to redirect to when the form is valid. Let\u2019s do the \u201ceasy\u201d one first, the success page.<\/p>\n\n\n\n
    #[get(\"\/hi?<name>\")]\nasync fn hello(name: String, flash: Option<FlashMessage<'_>>) -> Template {\n    let message = flash.map_or_else(|| String::default(), |msg| msg.message().to_string());\n    Template::render(\"hello\", context! { name , message })\n}\n<\/pre>\n\n\n\n
    A few important things are happening in this function.<\/p>\n\n\n\n
      \n
    1. We are receiving a FlashMessage<\/code>, information stored in a cookie from the previous endpoint. We\u2019ll see how you can set this value soon.<\/li>\n\n\n\n
    2. We are pulling the name<\/code> value from the query string.<\/li>\n<\/ol>\n\n\n\n
      Note that this is a demonstration of what Rocket provides as essential features of a web framework. You can experiment with this and pass all the values through the FlashMessage<\/code> or the query string.<\/p>\n\n\n\n
      Next, we\u2019ll delve into the most complex part of this sample application, the POST<\/code> endpoint. Before looking at the code, let\u2019s discuss the behavior we want.<\/p>\n\n\n\n