Leptos Axum Starter Template Hosted on Shuttle.rs

STATUS: Local development of a Leptos-Shuttle project is working; however, Shuttle.rs IS NOT working for cloud deploys of Leptos apps. Contributions & fixes are welcome.

Note: This Leptos starter template has been modified to deploy to Shuttle.rs

For further details and for updates, see here: shuttle-hq/shuttle#1002 (comment)

---

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

If you don't have cargo-generate installed already, install it with

cargo install cargo-generate

Then run

cargo generate --git https://github.com/Rust-WASI-WASM/shuttle-leptos-axum.git

Currently, to run Leptos Shuttle locally, you must run in --release mode to generate a new project template. Then

cd {{project-name}}

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.

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.

1. rustup toolchain install nightly --allow-downgrade - make sure you have Rust nightly
2. rustup target add wasm32-unknown-unknown - add the ability to compile Rust to WebAssembly
3. cargo install cargo-generate - install cargo-generate binary (should be installed automatically in future)
4. npm install -g sass - install dart-sass (should be optional in future)

Setting Up Shuttle.rs

First, make sure you have the Shuttle.rs CLI: run

cargo install cargo-shuttle

to install the Shuttle CLI. Then, to log in to Shuttle, run

cargo shuttle login

When the Shuttle webpage opens, copy the API key and enter it into the Shuttle CLI.

In your project folder, run

cargo shuttle project start

to initiate your new project with Shuttle. At this point, you can either run your project locally using the command

cargo shuttle run --release

NB: cargo shuttle run by itself does not work - release mode must be used.

Or you can deploy to Shuttle.rs manually using the command

cargo leptos build --release && cargo shuttle deploy

Note: If you update the dependencies of your project, you'll need to re-initiate your Shuttle project using

cargo shuttle project restart

If you find that your deployed project does not look like it's updating, you may need to run the following commands in your project folder:

cargo clean
cargo leptos build --release && cargo shuttle deploy

Running your Shuttle project locally

cargo shuttle run --release

While Shuttle's normal dev workflow can be run with cargo shuttle run, currently, to run Leptos Shuttle locally, you must run in --release mode to bypass issues with hydration.

Compiling for Release

Note: Shuttle.rs does not officially support Leptos in SSR mode. As of now, the following instructions DO NOT lead to a working Leptos SSR deploy to Shuttle.rs. You are welcome to make any contributions that will help remedy this issue.

cargo leptos build --release

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

cargo shuttle deploy

will deploy your updated application to Shuttle.rs.

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.