This is a template for use with the Leptos web framework and the cargo-leptos tool using Axum.
If you don't have cargo-leptos
installed you can install it with
cargo install cargo-leptos
Then run
cargo leptos new --git leptos-rs/start-axum
to generate a new project template.
cd nexus
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
.
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 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:
nexus
site/
Set the following environment variables (updating for your project as needed):
LEPTOS_OUTPUT_NAME="nexus"
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.
To build and deploy your project to AWS, you'll need cargo-lambda. They provide installation instructions on their site.
Let's start by building the project with cargo-leptos
:
cargo leptos build --release
We won't use the server binary that it builds, since the Lambda function
requires a particular architecture that cargo-lambda
will handle for us. If
you'd rather not build the server twice, you'll have to manage the wasm build
and optimization yourself.
Next, let's build the production server binary:
LEPTOS_OUTPUT_NAME=aws-lambda cargo lambda build --no-default-features --features=ssr --release
This should produce a binary at target/lambda/aws-lambda/bootstrap
.
Cargo.toml
exposes all the required environment variables to cargo-lambda
so
that the server can run in production.
Finally, we can deploy the project to AWS:
cargo lambda deploy --include target/site --enable-function-url
After a few seconds, cargo-lambda
should print out the URL of your deployed
function!
You'll need AWS credentials with some permissions for IAM and Lambda operations.
cargo-lambda
provides the
minimum requirements here.
Setting up permissions can be a bit onerous if this is your first time working with AWS. For a quick and dirty setup, you can:
- Create a new user in the IAM service (Access Management > Users)
- Click "Attach policies directly" on the "Set permissions" page
- Add the "AWSLambda_FullAccess" and "IAMFullAccess" policies, and complete the user creation
- Create an access key for the user (don't worry about the warning)
- Place the access key and secret key in
~/.aws/credentials
(or wherever the appropriate location is for your system):
[default]
aws_access_key_id = AKIAQYLPMN5HCTNK35FD
aws_secret_access_key = rbWHpaI/lJnXdLteWHNnTVZpQztMB2+pdbb+KVgr
Serving static files from a lambda function is not the best approach. Ideally, you should upload your files to a CDN and configure your project to serve them from that location. AWS has an article on deploying React with SSR.
It's also pretty easy to set up edge compute with Lambda@Edge, which should improve latency.