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. Current templates include
  • https://github.com/leptos-rs/start: 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
• 'no_downloads' feature to allow user management of optional dependencies
  

Getting started

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

Dependencies

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\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

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:

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

# more configuration parameters...

Note the double braces: 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

# Sets the name of the binary target used.
#
# Optional, only necessary if the bin-package defines more than one target. Can also be set with the LEPTOS_BIN_TARGET=name env var
bin-target = "my-bin-name"

# Enables additional file hashes on outputted css, js, and wasm files
#
# Optional: Defaults to false. Can also be set with the LEPTOS_HASH_FILES=false env var (must be set at runtime too)
hash-files = false

# Sets the name for the file cargo-leptos uses to track the most recent hashes
#
# Optional: Defaults to "hash.txt". Can also be set with the LEPTOS_HASH_FILE_NAME="hash.txt" env var
hash-file-name = "hash.txt"

# The features to use when compiling all targets
#
# Optional. Can be extended with the command line parameter --features
features = []

# The features to use when compiling the bin target
#
# Optional. Can be over-ridden with the command line parameter --bin-features
bin-features = ["ssr"]

# If the --no-default-features flag should be used when compiling the bin target
#
# Optional. Defaults to false.
bin-default-features = false

# The profile to use for the bin target when compiling for release
#
# Optional. Defaults to "release".
bin-profile-release = "my-release-profile"

# The profile to use for the bin target when compiling for debug
#
# Optional. Defaults to "debug".
bin-profile-dev = "my-debug-profile"

# The target triple to use when compiling the bin target
#
# Optional. Env: LEPTOS_BIN_TARGET_TRIPLE
bin-target-triple = "x86_64-unknown-linux-gnu"

# The features to use when compiling the lib target
#
# Optional. Can be over-ridden with the command line parameter --lib-features
lib-features = ["hydrate"]

# If the --no-default-features flag should be used when compiling the lib target
#
# Optional. Defaults to false.
lib-default-features = false

# The profile to use for the lib target when compiling for release
#
# Optional. Defaults to "release".
lib-profile-release = "my-release-profile"

# The profile to use for the lib target when compiling for debug
#
# Optional. Defaults to "debug".
lib-profile-dev = "my-debug-profile"

# Fixes cargo bug that prevents incremental compilation (see #203)
#
# Optional. Defaults to false prior to 0.2.3, unconditionally enabled (with the setting becoming deprecated) since 0.2.3 and #216
separate-front-target-dir = true

# Pass additional parameters to the cargo process compiling to WASM
#
# Optional. No default
lib-cargo-args = ["--timings"]

# Pass additional parameters to the cargo process to build the server
#
# Optional. No default
bin-cargo-args = ["--timings"]

# The command to run instead of "cargo" when building the server
#
# Optional. No default. Env: LEPTOS_BIN_CARGO_COMMAND
bin-cargo-command = "cross"

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.

# Sets the name of the output js, wasm and css files.
#
# Optional, defaults to the lib package name or, in a workspace, the project name. Env: LEPTOS_OUTPUT_NAME.
output-name = "myproj"

# The site root folder is where cargo-leptos generate all output.
# NOTE: It is relative to the workspace root when running in a workspace.
# WARNING: all content of this folder will be erased on a rebuild!
#
# Optional, defaults to "/site" in the Cargo target directory. Env: LEPTOS_SITE_ROOT.
site-root = "target/site"

# The site-root relative folder where all compiled output (JS, WASM and CSS) is written.
#
# Optional, defaults to "pkg". Env: LEPTOS_SITE_PKG_DIR.
site-pkg-dir = "pkg"

# The source style file. If it ends with _.sass_ or _.scss_ then it will be compiled by `dart-sass`
# into CSS and processed by lightning css. When release is set, then it will also be minified.
#
# Optional. Env: LEPTOS_STYLE_FILE.
style-file = "style/main.scss"

# The tailwind input file.
#
# Optional, Activates the tailwind build
tailwind-input-file = "style/tailwind.css"

# The tailwind config file.
#
# Optional, defaults to "tailwind.config.js" which if is not present
# is generated for you
tailwind-config-file = "tailwind.config.js"

# The browserlist https://browsersl.ist query used for optimizing the CSS.
#
# Optional, defaults to "defaults". Env: LEPTOS_BROWSERQUERY.
browserquery = "defaults"

# Assets source dir. All files found here will be copied and synchronized to site-root.
# The assets-dir cannot have a sub directory with the same name/path as site-pkg-dir.
#
# Optional. Env: LEPTOS_ASSETS_DIR.
assets-dir = "assets"

# JS source dir. `wasm-bindgen` has the option to include JS snippets from JS files
# with `#[wasm_bindgen(module = "/js/foo.js")]`. A change in any JS file in this dir
# will trigger a rebuild.
#
# Optional. Defaults to "src"
js-dir = "src"

# Additional files your application could depends on.
# A change to any file in those directories will trigger a rebuild.
#
# Optional.
watch-additional-files = ["additional_files", "custom_config.json"]

# The IP and port where the server serves the content. Use it in your server setup.
#
# Optional, defaults to 127.0.0.1:3000. Env: LEPTOS_SITE_ADDR.
site-addr = "127.0.0.1:3000"

# The port number used by the reload server (only used in watch mode).
#
# Optional, defaults 3001. Env: LEPTOS_RELOAD_PORT
reload-port = 3001

# The command used for running end-to-end tests. See the section about End-to-end testing.
#
# Optional. Env: LEPTOS_END2END_CMD.
end2end-cmd = "npx playwright test"

# The directory from which the end-to-end tests are run.
#
# Optional. Env: LEPTOS_END2END_DIR
end2end-dir = "integration"

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_CARGO_GENERATE_VERSION
• LEPTOS_TAILWIND_VERSION
• LEPTOS_SASS_VERSION
• LEPTOS_WASM_OPT_VERSION

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.