Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
C

cargo-leptos

> 编程语言
Open source

Build tool for Leptos (Rust)

544 stars0 likes1 views
WebsiteGitHub

About

Build tool for Leptos (Rust)

Build tool for Leptos:

  • Features
  • Getting started
    • Dependencies
  • Single-package setup
  • Workspace setup
  • Build features
  • Parameters reference
    • Compilation parameters
    • Site parameters
    • Environment variables
    • End-to-end testing

Features

  • Parallel build of server and client in watch mode for fast developer feedback.
  • CSS hot-reload (no page-reload, only CSS updated).
  • Build server and client for hydration (client-side rendering mode not supported).
  • Support for both workspace and single-package setup.
  • SCSS compilation using dart-sass.
  • CSS transformation and minification using Lightning CSS.
  • Builds server and client (wasm) binaries using Cargo.
  • Generates JS - Wasm bindings with wasm-bindgen
    • Includes support for JS Snippets for when you want to call some JS code from your WASM.
  • Optimises the wasm with wasm-opt from Binaryen
  • 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.
  • 'no_downloads' feature to allow user management of optional dependencies

Getting started

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 starter
  • https://github.com/leptos-rs/start-axum: An Axum starter
  • https://github.com/leptos-rs/start-axum-workspace: An Axum starter keeping client and server code in separate crates in a workspace

Dependencies

The 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

Completions

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

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

Single-package setup

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)

Workspace setup

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]]
# 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.

Build features

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

Parameters reference

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.

Compilation parameters

…

Site parameters

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.

…

Environment variables

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:

  • LEPTOS_OUTPUT_NAME
  • LEPTOS_SITE_ROOT
  • LEPTOS_SITE_PKG_DIR
  • LEPTOS_SITE_ADDR
  • LEPTOS_RELOAD_PORT

Directories used when building:

  • LEPTOS_LIB_DIR: The path (relative to the working directory) to the library package
  • LEPTOS_BIN_DIR: The path (relative to the working directory) to the binary package

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.
  • the two are set to the same value when running in a single-package config.
  • Avoid using them at run-time unless you can guarantee that the entire project struct is available at runtime as well.

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):

  • LEPTOS_TAILWIND_VERSION
  • LEPTOS_SASS_VERSION

During build

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:

toml
[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.

End-to-end testing

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:

  • in a terminal, run cargo leptos watch
  • in a separate terminal, change to the end2end-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.

Note: wasm-bindgen version management

cargo-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:

  • detect whether you have wasm-bindgen-cli installed locally
  • detect the version of wasm-bindgen that's in your lockfile
  • download and install a corresponding wasm-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.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rust

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言