Leptos Axum Starter Template

This is a template for use with the Leptos web framework and the cargo-leptos tool using Axum.

Creating your template repo

If you don't have cargo-leptos installed you can install it with

cargo install cargo-leptos

Then run

cargo leptos new --git https://github.com/leptos-rs/start-axum-workspace/

to generate a new project template.

cd {projectname}

to go to your newly created project.
Feel free to explore the project structure, but the best place to start with your application code is in src/app.rs.
Addtionally, Cargo.toml may need updating as new versions of the dependencies are released, especially if things are not working after a cargo update.

Running your project

cargo leptos watch

Installing Additional Tools

By default, cargo-leptos uses nightly Rust, cargo-generate, and sass. If you run into any trouble, you may need to install one or more of these tools.

rustup toolchain install nightly --allow-downgrade - make sure you have Rust nightly
rustup default nightly - setup nightly as default, or you can use rust-toolchain file later on
rustup target add wasm32-unknown-unknown - add the ability to compile Rust to WebAssembly
cargo install cargo-generate - install cargo-generate binary (should be installed automatically in future)
npm install -g sass - install dart-sass (should be optional in future

Compiling for Release

cargo leptos build --release

Will generate your server binary in target/server/release and your site package in target/site

Testing Your Project

cargo leptos end-to-end

cargo leptos end-to-end --release

Cargo-leptos uses Playwright as the end-to-end test tool.
Tests are located in end2end/tests directory.

Executing a Server on a Remote Machine Without the Toolchain

After running a cargo leptos build --release the minimum files needed are:

The server binary located in target/server/release
The site directory and all files within located in target/site

Copy these files to your remote server. The directory structure should be:

start-axum
site/

Set the following enviornment variables (updating for your project as needed):

LEPTOS_OUTPUT_NAME="start-axum"
LEPTOS_SITE_ROOT="site"
LEPTOS_SITE_PKG_DIR="pkg"
LEPTOS_SITE_ADDR="127.0.0.1:3000"
LEPTOS_RELOAD_PORT="3001"

Finally, run the server binary.