Build tool for Leptos (Rust)
Build tool for Leptos:
watch command for automatic rebuilds with browser live-reload.test command for running tests of the lib and bin packages that makes up the Leptos project.build build the server and client.end-to-end command for building, running the server and calling a bash shell hook. The hook would typically launch Playwright or similar.new command for creating a new project based on templates, using cargo-generate.Install:
cargo install --locked cargo-leptos
Note that this may require additional dependencies for SSL on some systems.
If the installation fails while building openssl-sys, you will need to
install additional tools,
before retrying the build.
If you, for any reason, need the bleeding-edge super fresh version:
cargo install --git https://github.com/leptos-rs/cargo-leptos --locked cargo-leptos
Help:
cargo leptos --help
For setting up your project, have a look at one of the templates or the examples. You can also use the cargo leptos new command to create a new project from a template, see cargo leptos new --help for more information.
Current templates include but are not limited to:
https://github.com/leptos-rs/start-actix: An Actix starterhttps://github.com/leptos-rs/start-axum: An Axum starterhttps://github.com/leptos-rs/start-axum-workspace: An Axum starter keeping client and server code in separate crates in a workspaceThe dependency for sass is automatically installed in a cache directory when they are used if they are not already installed and found by which. Different versions of the dependencies might accumulate in this directory, so feel free to delete it.
| OS | Example |
|---|---|
| Linux | /home/alice/.cache/cargo-leptos |
| macOS | /Users/Alice/Library/Caches/cargo-leptos |
| Windows | C:\Users\Alice\AppData\Local\cargo-leptos |
If you wish to make it mandatory to install your dependencies, or are using Nix or NixOs, you can
install it with the no_downloads feature enabled to prevent cargo-leptos from trying to download and install them.
cargo install --features no_downloads --locked cargo-leptos
For at least some shells (bash and zsh are confirmed to work) cargo is able to forward completions from custom
commands like cargo leptos back to the underlying cargo-leptos binary.
For that purpose cargo-leptos supports generating completions using cargo leptos completions .
Which you then can install/source for your shell. For bash, the command could like this
cargo leptos completions bash > "${XDG_DATA_HOME:-"$HOME/.local/share}/bash-completion/completions/cargo-leptos"The single-package setup is where the code for both the frontend and the server is defined in a single package.
Configuration parameters are defined in the package Cargo.toml section [package.metadata.leptos]. See the Parameters reference for
a full list of parameters that can be used. All paths are relative to the package root (i.e. to the Cargo.toml file)
When using a workspace setup both single-package and multi-package projects are supported. The latter is when the frontend and the server reside in different packages.
All workspace members whose Cargo.toml define the [package.metadata.leptos] section are automatically included as Leptos
single-package projects. The multi-package projects are defined on the workspace level in the Cargo.toml's
section [[workspace.metadata.leptos]] which takes three mandatory parameters:
[[workspace.metadata.leptos]]
# project name
name = "leptos-project"
bin-package = "server"
lib-package = "front"
# more configuration parameters...Note the double square brackets: several projects can be defined and one package can be used in several projects.
When building with cargo-leptos, the frontend, library package, is compiled into wasm using target
wasm-unknown-unknown and the features --no-default-features --features=hydrate
The server binary is compiled with the features --no-default-features --features=ssr
These parameters are used either in the workspace section [[workspace.metadata.leptos]] or the package,
for single-package setups, section [package.metadata.leptos].
Note that the Cargo Manifest uses the word target with two different meanings.
As a package's configured [[bin]] targets and as the compiled output target triple.
Here, the latter is referred to as target-triple.
…These parameters can be overridden by setting the corresponding environment variable. They can also be
set in a .env file as cargo-leptos reads the first it finds in the package or workspace directory and
any parent directory.
…The following environment variables are set when compiling the lib (front) or bin (server) and when the server is run.
Echoed from the Leptos config:
Directories used when building:
Note when using directories:
cargo-leptos changes the working directory to the project root or if in a workspace, the workspace root before building and running.Internally the versions of the external tools called by cargo-leptos are hardcoded. Use these environment variables to
override the versions cargo-leptos should use (e.g. LEPTOS_SASS_VERSION=1.69.5):
During the build process, cargo-leptos injects several environment variables. With cross, only a subset of environment variables are passed into the container during the build.
For cross specifically, you need to add this section to the Cross.toml file:
[build.env]
passthrough = [
"LEPTOS_OUTPUT_NAME",
"LEPTOS_SITE_ROOT",
"LEPTOS_SITE_PKG_DIR",
"LEPTOS_SITE_ADDR",
"LEPTOS_RELOAD_PORT",
"LEPTOS_LIB_DIR",
"LEPTOS_BIN_DIR",
"LEPTOS_JS_MINIFY",
"LEPTOS_HASH_FILES",
"RUSTFLAGS",
]Other tools need to accept the same environment variables. If this is not done correctly, then the WASM files are not linked correctly. See issue #574 for more details.
cargo-leptos provides end-to-end testing support for convenience. It is a simple
wrapper around a shell command end2end-cmd that is executed in a specific directory end2end-dir.
The end2end-cmd can be any shell command. For running Playwright it
would be npx playwright test.
What it does is equivalent to running this manually:
cargo leptos watchend2end-dir and run the end2end-cmd.When testing the setup, please try the above first. If that works but cargo leptos end-to-end
doesn't then please create a GitHub ticket.
wasm-bindgen version managementcargo-leptos supports automatically downloading binary dependencies for tools like wasm-bindgen-cli.
wasm-bindgen-cli requires a direct match between the patch version of the wasm-bindgen crate and the patch version of the wasm-bindgen-cli tool. This can sometimes make dependency management more complicated, because it means that cargo may resolve your wasm-bindgen version to a later patch version of the crate, causing a mismatched with your installed wasm-bindgen-cli version.
Currently, cargo-leptos will:
wasm-bindgen-cli installed locallywasm-bindgen that's in your lockfilewasm-bindgen-cli version locally if you don't have wasm-bindgen-cli installed.It does not download an updated or downgraded version if it finds wasm-bindgen-cli installed globally. If you have wasm-bindgen-cli installed globally, you will need to manage the verison manually. In the case of a mismatch, wasm-bindgen-cli emits an error message with precise instructions on how to either a) upgrade or downgrade wasm-bindgen-cli or b) pin the wasm-bindgen crate to the corresponding version.
No open issues yet, or sync has not completed.