---

name: leptos description: >- Leptos is a Rust web framework that builds reactive user interfaces compiled to WebAssembly, either as a client-side app or as a full-stack app with server-side rendering, hydration and server functions on Axum or Actix. Use when a user asks to "build a web app in Rust", "start a Leptos project", "add a server function", "use signals and resources in Leptos", "set up cargo-leptos", "fix Leptos code that no longer compiles after 0.7", or "deploy a Leptos SSR app". Covers Leptos 0.8: signals, the view macro, resources and Suspense, server functions and actions, routing, islands, Trunk and cargo-leptos. license: Apache-2.0 compatibility: "Rust stable with the wasm32-unknown-unknown target. Client-side apps need Trunk; full-stack apps need cargo-leptos and Axum 0.8 or Actix. Compiled against leptos 0.8.21 on Rust 1.99." metadata: author: terminal-skills version: 1.1.0 category: development repository: https://github.com/leptos-rs/leptos tags: - rust - wasm - full-stack - reactive - ssr

Leptos — Full-Stack Rust Web Framework

Overview

Leptos renders HTML from Rust components written with the view! macro and updates the page through fine-grained signals: when a signal changes, only the DOM nodes that read it are touched. It runs in two modes:

• Client-side rendering (CSR) — the app compiles to WebAssembly and is served as static files by Trunk. Fast builds, any backend.
• Server-side rendering (SSR) with hydration — one crate compiles twice: a native server binary (feature ssr) that renders HTML, and a WebAssembly bundle (feature hydrate) that makes it interactive. cargo-leptos coordinates both builds, and server functions let client code call server code directly.

Leptos 0.7 rewrote the API, and 0.8 keeps it. Code from older tutorials (use leptos::*, create_signal, create_resource, .into_view() on every branch) fails or warns: the current forms are use leptos::prelude::*, signal(), Resource::new(), .into_any().

Instructions

1. Set up the toolchain

Rust comes from rustup (use your distribution's rustup package, or download rustup-init and check it against the .sha256 published next to it). Then:

rustup target add wasm32-unknown-unknown
cargo install --locked trunk            # CSR apps
cargo install --locked cargo-leptos     # full-stack apps

Stable Rust is enough. The nightly feature of leptos only adds function-call syntax for signals (count() instead of count.get()).

2. Client-side app with Trunk

cargo init reading-timer && cd reading-timer
cargo add leptos --features=csr
cargo add console_error_panic_hook
printf '<!DOCTYPE html>\n<html>\n  <head></head>\n  <body></body>\n</html>\n' > index.html
trunk serve --open                      # rebuilds and reloads on save
trunk build --release                   # static site in dist/

// src/main.rs
use leptos::prelude::*;

#[component]
fn Counter(#[prop(default = 0)] initial: i32, #[prop(into)] label: String) -> impl IntoView {
    let (count, set_count) = signal(initial);
    let doubled = Memo::new(move |_| count.get() * 2);
    Effect::new(move |_| leptos::logging::log!("count is {}", count.get()));

    view! {
        <button on:click=move |_| set_count.update(|n| *n -= 1)>"-"</button>
        <span class:negative=move || count.get() < 0>{label} ": " {count} " (doubled: " {doubled} ")"</span>
        <button on:click=move |_| *set_count.write() += 1>"+"</button>
        <Show when=move || { count.get() > 9 } fallback=|| view! { <p>"Keep going"</p> }>
            <p>"Double digits"</p>
        </Show>
    }
}

fn main() {
    console_error_panic_hook::set_once();
    leptos::mount::mount_to_body(|| view! { <Counter initial=3 label="Clicks"/> });
}

What to know about signals and the view macro:

• signal(v) returns a (ReadSignal, WriteSignal) pair; RwSignal::new(v) is one handle for both. Read with .get() (clones) or .read() (borrows); write with .set(v), .update(|v| ...) or *sig.write() = v. All are Copy, so move closures can capture them freely.
• A value is reactive in the view only if it is a signal or a closure: {count} and {move || count.get() * 2} update, {count.get()} is evaluated once.
• Memo::new caches a derived value; Effect::new runs side effects in the browser after render and never on the server.
• Text nodes are string literals in quotes. Attributes: on:click=, class:name=, style:color=, prop:value=, and bind:value=signal for two-way input binding.
• Branches of an if/match inside view! must have one type: end each branch with .into_any() or use <Show>. Lists use <For each=... key=... children=.../> with a stable key.

3. Full-stack project with cargo-leptos

cargo leptos new --git https://github.com/leptos-rs/start-axum --name reading-list   # or .../start-actix
cd reading-list
cargo leptos watch                      # http://127.0.0.1:3000, rebuilds server and client
cargo leptos build --release            # target/release/reading-list + target/site/

cargo leptos new is a wizard: it asks "Use nightly features?" (answer No) and stops with IO error: not a terminal in a script or agent session. There, run cargo generate --git https://github.com/leptos-rs/start-axum --name reading-list -d nightly=No instead (cargo install --locked cargo-generate). The template's Cargo.toml wires the two builds. Keep this shape when adding dependencies: server-only crates are optional and listed under ssr.

[dependencies]
leptos = { version = "0.8" }
leptos_router = { version = "0.8" }
leptos_meta = { version = "0.8" }
serde = { version = "1", features = ["derive"] }                                        # added
axum = { version = "0.8", optional = true }
leptos_axum = { version = "0.8", optional = true }
tokio = { version = "1", features = ["rt-multi-thread"], optional = true }
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres"], optional = true }   # added
console_error_panic_hook = { version = "0.1", optional = true }
wasm-bindgen = { version = "0.2", optional = true }

[features]
hydrate = ["leptos/hydrate", "dep:console_error_panic_hook", "dep:wasm-bindgen"]
ssr = ["dep:axum", "dep:tokio", "dep:leptos_axum", "dep:sqlx", "leptos/ssr", "leptos_meta/ssr", "leptos_router/ssr"]

[package.metadata.leptos] in the same file sets site-root, site-addr (default 127.0.0.1:3000), bin-features = ["ssr"] and lib-features = ["hydrate"].

src/lib.rs exports hydrate(), which calls leptos::mount::hydrate_body(App); src/app.rs holds shell() (the HTML document with <HydrationScripts options/>) and the App component; src/main.rs is the server. To give server functions a database pool, pass it as context when registering routes:

// src/main.rs (inside #[cfg(feature = "ssr")] #[tokio::main] async fn main)
use axum::Router;
use leptos::prelude::*;
use leptos_axum::{generate_route_list, LeptosRoutes};
use reading_list::app::{shell, App};

let database_url = std::env::var("DATABASE_URL").expect("DATABASE_URL is not set");
let pool = sqlx::postgres::PgPoolOptions::new().max_connections(5).connect(&database_url).await.expect("database");

let conf = get_configuration(None).unwrap();
let addr = conf.leptos_options.site_addr;
let leptos_options = conf.leptos_options;
let routes = generate_route_list(App);

let app = Router::new()
    .leptos_routes_with_context(
        &leptos_options,
        routes,
        move || provide_context(pool.clone()),          // visible to components and server functions
        {
            let leptos_options = leptos_options.clone();
            move || shell(leptos_options.clone())
        },
    )
    .fallback(leptos_axum::file_and_error_handler(shell))
    .with_state(leptos_options);

let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
axum::serve(listener, app.into_make_service()).await.unwrap();

4. Server functions, resources and actions

// src/app.rs
use leptos::prelude::*;
use leptos_router::{components::{Route, Router, Routes, A}, hooks::use_params_map, path};
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "ssr", derive(sqlx::FromRow))]
pub struct Book {
    pub id: i64,
    pub title: String,
    pub author: String,
}

#[server]
pub async fn list_books() -> Result<Vec<Book>, ServerFnError> {
    let pool = expect_context::<sqlx::PgPool>();
    let books = sqlx::query_as::<_, Book>("SELECT id, title, author FROM books ORDER BY id DESC LIMIT 50")
        .fetch_all(&pool)
        .await?;
    Ok(books)
}

#[server]
pub async fn add_book(title: String, author: String) -> Result<(), ServerFnError> {
    if title.trim().is_empty() {
        return Err(ServerFnError::new("title is required"));
    }
    let pool = expect_context::<sqlx::PgPool>();
    sqlx::query("INSERT INTO books (title, author) VALUES ($1, $2)")
        .bind(title)
        .bind(author)
        .execute(&pool)
        .await?;
    Ok(())
}

#[component]
fn BookList() -> impl IntoView {
    let add = ServerAction::<AddBook>::new();
    // Refetches whenever the action finishes
    let books = Resource::new(move || add.version().get(), |_| list_books());

    view! {
        <ActionForm action=add>
            <input type="text" name="title" placeholder="Title"/>
            <input type="text" name="author" placeholder="Author"/>
            <button type="submit">"Add"</button>
        </ActionForm>
        <Suspense fallback=|| view! { <p>"Loading..."</p> }>
            <ErrorBoundary fallback=|errors| view! { <p class="error">{move || format!("{:?}", errors.get())}</p> }>
                <ul>
                    {move || Suspend::new(async move {
                        books.await.map(|books| {
                            books
                                .into_iter()
                                .map(|b| view! { <li><A href=format!("/books/{}", b.id)>{b.title}</A> " by " {b.author}</li> })
                                .collect_view()
                        })
                    })}
                </ul>
            </ErrorBoundary>
        </Suspense>
    }
}

#[component]
fn BookPage() -> impl IntoView {
    let params = use_params_map();
    let id = move || params.read().get("id").unwrap_or_default();
    view! { <h1>"Book #" {id}</h1> }
}

#[server] keeps the function body out of the WebAssembly build and generates an HTTP endpoint plus a client stub with the same signature. The macro also creates a struct named after the function in PascalCase (AddBook), which ServerAction and <ActionForm> use; the form's input names must match the argument names, and it works without JavaScript. Arguments and return values must implement Serialize and Deserialize. Routes go inside App (HomePage is the template's start page):

<Router>
    <Routes fallback=|| "Page not found.">
        <Route path=path!("/") view=HomePage/>
        <Route path=path!("/books") view=BookList/>
        <Route path=path!("/books/:id") view=BookPage/>
    </Routes>
</Router>

5. Islands and release builds

Islands mode ships no WebAssembly for static components. Enable the islands feature on leptos, mark interactive components with #[island] instead of #[component], call leptos::mount::hydrate_islands() in hydrate(), and write <HydrationScripts options islands=true/> in the shell.

The templates already build the WebAssembly bundle with a size-optimised profile ([profile.wasm-release] with opt-level = "z", LTO and one codegen unit, selected by lib-profile-release = "wasm-release"); keep it when editing Cargo.toml.

To deploy, copy the binary from target/release/ and the target/site/ directory to the server and set LEPTOS_SITE_ROOT=site and LEPTOS_SITE_ADDR=0.0.0.0:8080 (the address defaults to 127.0.0.1:3000, which is unreachable from outside a container).

Examples

Example 1: A counter page without a backend

User request:

I want to try Leptos. Make me a small page with a counter that I can open in the browser, no server.

The agent uses the commands and src/main.rs from section 2, then runs trunk serve --open. Trunk prints the address it serves (http://127.0.0.1:8080/ by default) and opens the page: Clicks: 3 (doubled: 6) with two buttons. Pressing "+" seven times shows Clicks: 10 (doubled: 20) and replaces "Keep going" with "Double digits"; the browser console logs count is 10. trunk build --release writes index.html, a .js loader and a .wasm file to dist/ for any static host.

Example 2: Add a database-backed page to a full-stack app

User request:

My start-axum project is called reading-list. Add a /books page that lists rows from Postgres and has a form to add one.

The agent adds serde and optional sqlx to Cargo.toml as in section 3, creates the pool in main.rs and passes it through leptos_routes_with_context, puts the Book struct, the two server functions and BookList from section 4 into src/app.rs, registers the /books routes, and verifies both halves compile:

cargo check --features ssr
cargo check --lib --features hydrate --target wasm32-unknown-unknown
DATABASE_URL="$READING_LIST_DATABASE_URL" cargo leptos watch

Both checks end with Finished. At http://127.0.0.1:3000/books the list is rendered into the HTML on the server; submitting the form calls add_book, the action's version changes, and the resource refetches the list without a page reload.

Guidelines

1. Pin the minor version — 0.6, 0.7/0.8 and the 0.9 beta are not source-compatible; keep leptos, leptos_router, leptos_meta and the server integration on the same line and check which version a tutorial targets.
2. Wrap comparisons in braces inside view! — when=move || count.get() > 9 does not parse because > closes the tag; write when=move || { count.get() > 9 }.
3. Server-only code must not reach the client build — make such dependencies optional, enable them in the ssr feature, and touch them only inside #[server] bodies or #[cfg(feature = "ssr")] items.
4. Server functions are public HTTP endpoints — validate input and check authentication inside every one; the client stub is not the only caller.
5. Hydration needs identical output — the server and the browser must render the same HTML; reading window, random values or the clock during render causes hydration errors. Do that work in Effect::new.
6. Context is typed — expect_context::<T>() panics when no value of that exact type was provided; use_context::<T>() returns an Option.
7. Load data with resources, mutate with actions — a Resource under <Suspense> streams in during SSR; make it depend on action.version() to refresh after writes.
8. Run both cargo check commands in CI — the ssr and hydrate builds fail independently.
9. Compile times are the cost — a full-stack rebuild compiles two targets; use CSR with Trunk when no server rendering is needed.