cargo-leptos

In a workspace setup, you can define multi-package projects where the frontend and server reside in different crates. These are defined at the workspace level in the root Cargo.toml using the [[workspace.metadata.leptos]] section.

Each project definition requires a name, a bin-package (the server), and a lib-package (the frontend).

Note the double square brackets [[...]], which allow you to define multiple projects within the same workspace.

[[workspace.metadata.leptos]]
# project name
name = "leptos-project"
bin-package = "server"
lib-package = "front"

# more configuration parameters...

cargo-leptos attempts to manage wasm-bindgen-cli versions automatically to ensure they match the wasm-bindgen crate version in your lockfile.

• Automatic Behavior: If wasm-bindgen-cli is not installed locally, cargo-leptos will detect the version in your lockfile and download the matching CLI version.
• Global Installation Warning: If you have wasm-bindgen-cli installed globally, cargo-leptos will not download a different version. You must manage the version manually to avoid mismatches.
• Troubleshooting: If a mismatch occurs, wasm-bindgen-cli will provide instructions on how to either upgrade/downgrade the CLI or pin the wasm-bindgen crate to a specific version.

If you are using cross for cross-compilation, you must explicitly allow certain Leptos environment variables to pass through to the container during the build process. If these are not passed, WASM files may not link correctly.

Add the following to your 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",
]

Install the cargo-leptos build tool using Cargo. Note that you may need to install additional SSL dependencies (like openssl) on your system if the build fails while compiling openssl-sys.

To install the stable version:

cargo install --locked cargo-leptos

To install the bleeding-edge version from GitHub:

cargo install --git https://github.com/leptos-rs/cargo-leptos --locked cargo-leptos

If you are using Nix or NixOS and want to prevent cargo-leptos from automatically downloading optional dependencies (like sass), install it with the no_downloads feature:

cargo install --features no_downloads --locked cargo-leptos

You can create a new Leptos project from a template using the cargo leptos new command. This uses cargo-generate under the hood.

Available templates include:

• https://github.com/leptos-rs/start-actix: An Actix starter
• https://github.com/leptos-rs/start-axum: An Axum starter
• https://github.com/leptos-rs/start-axum-workspace: An Axum starter with client and server in separate crates in a workspace

Run cargo leptos new --help for more information.

You can generate completions for bash and zsh using the cargo leptos completions <SHELL> command.

Example for bash:

cargo leptos completions bash > "${XDG_DATA_HOME:-"$HOME/.local/share"}/bash-completion/completions/cargo-leptos"

When using the serve or watch commands, you can pass trailing arguments directly to the resulting binary. This is useful for passing flags to your application's own CLI or runtime.

To do this, append the arguments after the cargo-leptos command. The arguments are treated as trailing arguments for the binary being executed.

# Example: Passing a custom flag to your application via cargo-leptos
cargo-leptos watch -- --my-app-flag value

cargo-leptos provides a wrapper for running end-to-end tests. It executes a specified shell command in a specific directory. This is equivalent to running cargo leptos watch in one terminal and your test command in another.

• end2end-cmd: The shell command to run (e.g., npx playwright test). (Env: LEPTOS_END2END_CMD)
• end2end-dir: The directory from which the tests are executed. (Env: LEPTOS_END2END_DIR)

end2end-cmd = "npx playwright test"
end2end-dir = "integration"

When running cargo leptos watch or cargo leptos serve, you can configure how the server process terminates. Enabling graceful-shutdown allows cargo-leptos to send a signal (like SIGINT or SIGTERM) and wait for the application to clean up before escalating to a hard kill.

• graceful-shutdown: Enables/disables graceful termination. (Default: true. Env: LEPTOS_GRACEFUL_SHUTDOWN)
• graceful-shutdown-timeout-secs: Seconds to wait after the signal before escalating to SIGKILL (Unix) or TerminateProcess (Windows). (Default: 10. Env: LEPTOS_GRACEFUL_SHUTDOWN_TIMEOUT_SECS)
• graceful-shutdown-unix-signal: The Unix signal to use. (Default: SIGINT. Env: LEPTOS_GRACEFUL_SHUTDOWN_UNIX_SIGNAL). Note: On Windows, CTRL_BREAK_EVENT is always used.

When running in watch mode, cargo-leptos determines how to notify the browser/client based on the type of files that changed. This is managed via the ProductSet of the build outcomes:

If a build fails, the command logs a warning and clears the source changes to prevent an infinite loop of failed rebuilds, but it continues to watch for the next fix.

When configuring site-root in Cargo.toml, you can use special markers to refer to the Cargo target directory:

• CARGO_TARGET_DIR: Replaced with the actual Cargo target directory.
• CARGO_BUILD_TARGET_DIR: Replaced with the actual Cargo target directory.

Example: site-root = "CARGO_TARGET_DIR/site" will resolve to target/site (or your specific target directory).

[package.metadata.leptos]
site-root = "CARGO_TARGET_DIR/site"