Configuration#

A leptoskit project is configured by one file, leptoskit.toml, at the project root. Every command looks for it in the current directory and then in each parent, so you can run leptoskit from anywhere inside a project.

Every section and every key is optional. Unknown keys are an error, so a typo fails loudly instead of being ignored. New projects include an editor schema directive and schema_version = 0. This schema is unstable: breaking changes are expected until the first version 1 schema.

#:schema https://leptoskit.dev/schemas/leptoskit.v0.schema.json

schema_version = 0

[app]
name = "my_app"
version = "0.1.0"
default_platform = "web"
platforms = ["web", "ios", "android", "macos", "windows", "linux"]
render = "islands"

[serve]
address = "127.0.0.1"
port = 3000

[build]
client_package = "my_app_app"
features = []
rustflags = []

[bundle]
optimize = "smallest"
split = true
wasm_opt = true
precompress = true
budget_kib = 80

[native]
package_id = "com.example.myapp"
viewport_width = 390.0
viewport_height = 844.0

[codepush]
enabled = true
server = "https://updates.example.com"
channel = "production"
mandatory = false
staging_dir = "codepush"
public_keys = [
	"3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29",
]

[[plugins]]
name = "leptos_meta"
leptos = true

[app]#

platforms lists the platforms you can build: leptoskit build --platform <platform> refuses one that isn't listed, before compiling anything. default_platform is the one leptoskit build uses without --platform, and it must be in platforms. The list can't be empty or repeat an entry.

Listing a platform doesn't compile anything for it. Each build turns on one platform feature in your app crate, such as ios, and with it that platform's per-platform files.

"harmonyos" is also accepted, for the experimental HarmonyOS starter. It is not in the default list, because the six-platform project has no HarmonyOS app. Older projects may also use "native", which builds the platform in native.targets, or "server", which builds only the web server.

Render modes#

render decides the cargo features each side of a web build gets, following the leptos convention that every leptos app already uses:

A client-rendered app with a server package, such as one with an API or sign-in, runs that server under leptoskit dev and leptoskit serve, and the server serves dist/ itself. Without a server package, leptoskit's static server serves dist/.

The server-rendering modes need the server package to declare an ssr feature and the client to declare a hydrate feature, and islands needs both to depend on leptos directly. When one is missing, the build stops and tells you which package needs what. The small bundles guide walks through each mode.

[serve]#

[build]#

[bundle]#

What a release build ships: how hard the wasm client is optimized, how the output is compressed, and how much it may weigh. The small bundles guide explains each setting.

[theme]#

Design tokens for Tailwind var(--name) utilities. Omit the table when you don't use custom properties. Keys may be written with or without the leading --; both become --name at runtime.

[theme.colors]
brand = "#3b82f6"
ink = "black"

[theme.lengths]
gap = "1rem"
pad = "16px"

Install them once at app startup so native paint and the web :root sheet agree:

use leptoskit::prelude::*;

let (config, _) = LeptoskitConfig::load()?;
if let Some(theme) = &config.theme {
	Theme::install_maps(&theme.colors, &theme.lengths)?;
}

Theme::css() emits the same names as a :root rule; the web adapter prepends it automatically when anything is set. See CSS coverage.

[native]#

native.package_id defaults to com.leptoskit.<name>, with punctuation removed from the app name. Runtime plugin names belong in native.plugins. Each selected plugin must be a direct Cargo dependency of the selected platform's host package. See automatic plugin registration. A plugin left out of a platform's build answers every call with Unavailable there; set missing-plugins = "error" to fail the build instead, as described in plugins a platform can't run.

Each package id segment starts with an ASCII letter and contains only ASCII letters and digits. Change native.update_contract in a store release when plugin grants or native behavior change incompatibly. Shared app workspaces append the destination, such as mobile-v1/ios, so hosts reject another platform's update bundle.

[codepush]#

[codepush.provenance]#

Set it to make the iOS and Android apps install only code push releases that enough independent approvers rebuilt from your public GitHub source. Requiring source approvals walks through it.

All three keys are required. The app ships the policy, so changing it takes a store release.

[router]#

Deprecated: file routes are now a plugin, activated like any other:

[[plugins]]
name = "router"

[plugins.options]
dir = "src/routes" # optional, the default
output = "src/routes.rs" # optional; the default sits beside the directory

The [router] table still works and leptoskit migrate rewrites it into the plugin form. Without the plugin (or the table), leptoskit leaves src/routes/ alone.

[[plugins]]#

Each [[plugins]] table turns on one build plugin, which hooks into leptoskit build and leptoskit dev: it can generate code before cargo runs, adjust the build's cargo features, environment, and assets, run again before the dev and production servers start, answer its own plugin:<name> commands, and declare the native permissions and dependencies a generated host needs. These are not the runtime plugins that give native apps operating-system services; those are listed in native.plugins (see runtime plugins).

A plugin as a program#

A plugin with a command — or an executable named leptoskit-plugin-<name> on PATH — is a separate program rather than compiled-in tooling, so anyone can write one in any language. leptoskit runs it once per hook with a JSON envelope on standard input and reads one JSON reply from standard output: generate replies with the files it written, the build hooks reply with extra features, env, and rustflags, and the plugin's own plugin:<name> <command> commands reply with their exit code. A describe hook, asked once when the plugin resolves, declares the plugin's CLI namespace, supported platforms, and commands.

Scaffold one with leptoskit generate tool-plugin <dir>, install it with cargo install --path <dir>, and declare it:

[[plugins]]
name = "demo"
command = "leptoskit-plugin-demo"

Using the configuration from Rust#

leptoskit_config is the library behind the file, so tools and build scripts read exactly what the CLI reads:

use leptoskit_config::LeptoskitConfig;

let (config, root) = LeptoskitConfig::load().expect("a leptoskit.toml in this directory or a parent");
println!("{} at {}", config.app.name, root.display());