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.end2end 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. WIP: You'll need to ask on the Leptos discord for the url of a template.Install:
cargo install --locked cargo-leptos
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 the examples
The dependencies for sass, wasm-opt and cargo-generate are 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\Localcargo-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
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:
```toml [[workspace.metadata.leptos]]
name = "leptos-project" bin-package = "server" lib-package = "front"
```
Note the double braces: 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.
```toml
#
bin-target = "my-bin-name"
#
features = []
#
bin-features = ["ssr"]
#
bin-default-features = false
#
bin-profile-release = "my-release-profile"
#
bin-profile-debug = "my-debug-profile"
#
bin-target-triple = "x86_64-unknown-linux-gnu"
#
lib-features = ["hydrate"]
#
lib-default-features = false
#
lib-profile-release = "my-release-profile"
#
lib-profile-debug = "my-debug-profile" ```
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.
```toml
#
output-name = "myproj"
#
site-root = "target/site"
#
site-pkg-dir = "pkg"
dart-sass#
style-file = "style/main.scss"
#
tailwind-input-file = "style/tailwind.css"
#
tailwind-config-file = "./tailwind.config.js"
#
browserquery = "defaults"
#
assets-dir = "assets"
wasm-bindgen has the option to include JS snippets from JS files#[wasm_bindgen(module = "/js/foo.js")]. A change in any JS file in this dir#
js-dir = "src"
#
site-addr = "127.0.0.1:3000"
#
reload-port = 3001
#
end2end-cmd = "npx playwright test"
#
end2end-dir = "integration" ```
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.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.