Getting started

Create a Hearth app and run it locally with automatic updates as you edit.

Hearth 0.1.0 and hearth-cli 0.1.0 are published on crates.io. Use Rust 1.99.1, the tested toolchain. Node.js and pnpm are not needed for an application installed from the registry.

rustup toolchain install 1.99.1

Create a new project

Create a Cargo binary project:

cargo new hello-world
cd hello-world
rustup override set 1.99.1

Add hearth and tokio:

cargo add hearth@=0.1.0
cargo add tokio --features rt-multi-thread,macros

Replace src/main.rs with:

use hearth::{
    Result,
    router::{module_router, page},
    view::{View, component, view},
};

#[tokio::main]
async fn main() {
    hearth::start(module_router!().build()).await.unwrap();
}

#[page]
async fn home() -> Result<impl View> {
    Ok(view! {
        <!DOCTYPE html>
        <html>
            <head>
                <title>"Hello world"</title>
                hearth::dev::script()
            </head>
            <body>
                hello(name: "World")
            </body>
        </html>
    })
}

#[component]
async fn hello(name: &str) -> Result<impl View> {
    Ok(view! {
        <h1>"Hello, " (name) "!"</h1>
    })
}

module_router!() uses its enclosing module as /, so the home page above serves /. To add /about, declare mod about; in main.rs and put a #[page] handler in src/about.rs. See the module routing guide for nested modules, layouts, and path parameters.

Run cargo run --release to serve the app at http://127.0.0.1:3000. For automatic rebuilds while you work, install the Hearth CLI.

Install the CLI

Install the CLI from crates.io:

cargo install hearth-cli --version 0.1.0 --locked

Make sure Cargo's binary directory is on your PATH so you can run hearth. You can also invoke it as cargo hearth.

Start the dev server

From the project root:

hearth dev --release

The dev server builds and starts the app, then rebuilds it when source files change. Pages that include hearth::dev::script() update when the new build is ready. Press r in the terminal to rebuild manually.

Open http://127.0.0.1:3000 and you should see Hello, World!.

To override the bind address, set HOST and PORT before running:

HOST=0.0.0.0 PORT=8080 hearth dev --release

Improving build times

For ways to reduce rebuild times, see the Cargo book's build performance chapter.

Where to next

Choose your next topic from the guide index.