Leptos 的构建工具

• 功能
• 入门指南
  • 依赖项
• 单包设置
• 工作区设置
• 构建功能
• 参数参考
  • 编译参数
  • 站点参数
  • 环境变量
  • 端到端测试

功能

• 在监视模式下并行构建服务器和客户端以快速提供开发者反馈。
• CSS 热重载（无需重新加载页面，仅更新 CSS）。
• 为客户端渲染模式（不支持）构建服务器和客户端。
• 支持工作区和单包设置。
• 使用 dart-sass 编译 SCSS。
• 使用 Lightning CSS 进行 CSS 转换和最小化。
• 使用 Cargo 构建（wasm）服务器和客户端二进制文件。
• 使用 wasm-bindgen 生成 JS - Wasm 绑定。
  • 包括对 JS 片段 的支持，以便您从 WASM 调用一些 JS 代码。
• 使用 Binaryen 的 wasm-opt 对 wasm 进行优化。
• watch 命令用于在浏览器实时重新加载的情况下自动重新构建。
• test 命令用于运行构成 Leptos 项目的 lib 和 bin 包的测试。
• build 构建服务器和客户端。
• end-to-end 命令，用于构建、运行服务器和调用 bash shell 钩子。钩子通常用于启动 Playwright 或类似工具。
• new 命令，用于根据模板创建新项目，使用 cargo-generate。当前模板包括
  • https://github.com/leptos-rs/start：一个 Actix 入门项目
  • https://github.com/leptos-rs/start-axum：一个 Axum 入门项目
  • https://github.com/leptos-rs/start-axum-workspace：一个将客户端和服务器代码分别放在工作区不同crate中的 Axum 入门项目
• 'no_downloads' 功能，允许用户管理可选依赖项
  

入门指南

安装

cargoinstall --lockedcargo-leptos

如果您需要最新的版本，请使用以下命令：

cargoinstall --githttps://github.com/leptos-rs/cargo-leptos --lockedcargo-leptos

帮助

cargoleptos --帮助

关于设置您的项目，请参阅 示例

依赖项

当使用 sass、wasm-opt 和 cargo-generate 时，如果它们尚未安装并且由 which 找到，则它们会自动安装到一个缓存目录中。依赖项的不同版本可能会积累在这个目录中，因此您可以随意删除它。

如果您希望强制安装依赖项，或正在使用 Nix 或 NixOs，您可以通过启用 no_downloads 功能来安装它，以防止 cargo-leptos 尝试下载和安装它们。

cargoinstall --功能no_downloads --lockedcargo-leptos

单包设置

单包设置是将前端和服务器代码定义在单个包中的设置。

配置参数定义在包 Cargo.toml 的 [package.metadata.leptos] 部分中。有关可以使用参数的完整列表，请参阅参数参考。所有路径都是相对于包根目录（即 Cargo.toml 文件）的。

工作区设置

当使用工作区设置时，支持单包和多包项目。后者是前端和服务器位于不同包中的情况。

所有定义了 Cargo.toml 的 [package.metadata.leptos] 部分的工作区成员都将自动包括为 Leptos 单包项目。多包项目在工作区级别定义在 Cargo.toml 的 [[workspace.metadata.leptos]] 部分中，该部分需要三个必填参数

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

# more configuration parameters...

注意双大括号：可以定义多个项目，一个包可以用于多个项目。

构建功能

使用 cargo-leptos 构建时，前端库包使用目标 wasm-unknown-unknown 和功能 --no-default-features --features=hydrate 编译为 wasm。服务器二进制文件使用功能 --no-default-features --features=ssr 编译。

参数参考

这些参数用于工作区部分 [[工作区.元数据.leptos]] 或包中，对于单个包设置，部分 [package.metadata.leptos]。

请注意，Cargo清单使用单词 目标 有两种不同的含义。作为包配置的 [[bin]] 目标以及作为编译输出目标三元组。在这里，后者被称为 目标三元组。

编译参数

# 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"

站点参数

可以通过设置相应的环境变量来覆盖这些参数。它们也可以在 .env 文件中设置，因为 cargo-leptos 会读取包或工作区目录以及任何父目录中找到的第一个。

# 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"

环境变量

以下环境变量在编译库（前端）或二进制（服务器）时以及运行服务器时设置。

来自 Leptos 配置的输出

• LEPTOS_OUTPUT_NAME
• LEPTOS_SITE_ROOT
• LEPTOS_SITE_PKG_DIR
• LEPTOS_SITE_ADDR
• LEPTOS_RELOAD_PORT

构建时使用的目录

• LEPTOS_LIB_DIR: 从工作目录到库包的路径
• LEPTOS_BIN_DIR: 从工作目录到二进制包的路径

使用目录时的注意事项

• cargo-leptos 在构建和运行之前将工作目录更改为项目根目录或，如果在工作区中，则更改为工作区根目录。
• 当在单个包配置中运行时，这两个设置为相同的值。
• 除非您能保证整个项目结构在运行时也可用，否则请避免在运行时使用它们。

内部，cargo-leptos 调用的外部工具的版本是硬编码的。使用这些环境变量来覆盖 cargo-leptos 应使用的版本（例如，LEPTOS_SASS_VERSION=1.69.5）

• LEPTOS_CARGO_GENERATE_VERSION
• LEPTOS_TAILWIND_VERSION
• LEPTOS_SASS_VERSION
• LEPTOS_WASM_OPT_VERSION

端到端测试

cargo-leptos 提供端到端测试支持以方便使用。它是一个简单的包装程序，围绕在特定目录 end2end-dir 中执行的 shell 命令 end2end-cmd。

end2end-cmd 可以是任何 shell 命令。对于运行 Playwright，它将是 npx playwright test。

它执行的操作相当于手动执行以下命令

• 在终端中，运行 cargo leptos watch
• 在另一个终端中，切换到 end2end-dir 并运行 end2end-cmd。

在测试设置时，请首先尝试上述操作。如果那样做可以工作，但 cargo leptos end-to-end 不行，那么请创建一个 GitHub 问题。