This is a template for use with the Leptos web framework, the cargo-leptos tool using Axum, the multi-model database Surrealdb and the awesome component library web, Leptonic.
If you don't have cargo-leptos
installed you can install it with
cargo install cargo-leptos
Then run
cargo leptos new -n {projectname} --git https://github.com/tetuaoro/template-leptos-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
.
Note that for islands to work correctly, you need to have a use app;
in your frontend lib.rs
otherwise rustc / wasm_bindgen gets confused.
To prevent clippy from complaining, at the top of the frontend/lib.rs
file place:
#[allow(unused_imports)]
use app;
If you use surrealdb
crate for your database, you need to create .env
file at the root directory of the project with the following content :
SURREAL_NS=""
SURREAL_DB=""
SURREAL_BIND=""
SURREAL_USER=""
SURREAL_PASS=""
SURREAL_DEFINITION_SCHEMA_PATH=""
Replace the empty strings with the appropriate values for your project. All the variables are required while SURREAL_DEFINITION_SCHEMA_PATH
is optional.
N.B When your app is running, the instance runs with a random guess scope user to ensure security and permission access.
A starter template file SURREALDB_DEFINITION
is define in the root project.
To use the surrealdb
crate for database operations, you can use the get_db()
function provided. To initialize database at runtime, uncomment the main server function :
# server/src/main.rs
// services::get_db().await.expect("couldn't intialize database");
Here's an example of how to use the get_db()
function :
use services::get_db;
...
// somewhere inside an async fn
let client: Result<Surreal<_>, crate::error::Error> = db::get_db().await;
...
In this example, the get_db()
function is called inside an asynchronous function to obtain an instance of the database client. This instance can then be used for database operations.
cargo leptos watch
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 nightlyrustup default nightly
- setup nightly as default, or you can use rust-toolchain file later onrustup target add wasm32-unknown-unknown
- add the ability to compile Rust to WebAssemblycargo install cargo-generate
- installcargo-generate
binary (should be installed automatically in future)npm install -g sass
- installdart-sass
(should be optional in future
cargo leptos build --release
Will generate your server binary in target/server/release and your site package in target/site
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.
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 intarget/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.
This template itself is released under the Unlicense. You should replace the LICENSE for your own application with an appropriate license if you plan to release it publicly.