Basic Configuration
How Sweets loads, layers, and reloads your Lua configuration.
Sweets is configured in Lua. On startup it loads the packaged defaults first, then layers your user config on top.
Load order
Packaged defaults are loaded first:
/usr/share/sweets/sweets.luaOr the equivalent sweets/sweets.lua under the Meson install datadir.
Your user config is loaded next, when present:
$XDG_CONFIG_HOME/sweets/sweets.luaFalling back to ~/.config/sweets/sweets.lua when XDG_CONFIG_HOME is
unset.
User settings and bindings layer over the packaged defaults. Binding the same key combo again replaces the earlier default binding.
Either file can pull in additional Lua files with
sweets.include(...), so you can split a
large config into focused pieces.
Fail-safe behavior
A broken config never crashes the compositor:
- If the user file is missing, Sweets uses the packaged defaults as-is.
- If no Lua file provides any bindings, Sweets falls back to a tiny emergency C binding set so the compositor stays controllable.
- If an existing Lua file contains an error, Sweets logs it, keeps the previous configuration — the emergency defaults at startup, or the last good config on reload — and shows the error on screen (see below).
Error reporting
When a config fails to load or reload — a syntax error, an unknown field, or an invalid value such as a malformed color — Sweets shows a red bar across the top of every monitor with the failing file, line, and message. The compositor keeps running on the last good configuration the whole time.
The bar clears itself automatically the moment a later edit reloads cleanly, so
fixing and saving the file makes it disappear. You can also dismiss it manually
by clicking any monitor's bar, or with the dismiss_error key binding; both
clear the bar on every monitor at once, and a dismissed bar returns on the next
failed reload.
The bar is drawn by a small helper, sweetnag, installed alongside the
compositor. You can preview it at any time with
echo "example error" | sweetnag. Its colors and font are configurable
through sweets.notify{ ... }.
Automatic reload
Sweets watches the packaged defaults, your user config, and every
included file while it runs. Saving any
of them, creating sweets.lua after startup, replacing it atomically, or
deleting it automatically triggers a fail-safe reload after a short debounce.
Manual reload is always available with MOD + Shift + R or
sweetctl reload.
The sweets table
The global sweets table is available to your config script. Each section of
the API configures a different part of the compositor:
| Call | Configures |
|---|---|
sweets.general{ ... } | Modifier key, background, workspace and cross-monitor behavior |
sweets.layout{ ... } | Master/stack tiling, gaps, and window borders |
sweets.notify{ ... } | Colors and font of the on-screen config-error bar |
sweets.keyboard{ ... } / sweets.cursor{ ... } | Keyboard repeat and numlock, cursor size and theme |
sweets.pointer{ ... } | Automatic pointer-follow after focus and workspace changes |
sweets.input(...) | libinput pointer device settings, globally or per-device |
sweets.monitor(...) | Output rules — resolution, scale, position, transform |
sweets.workspace(...) | Pin workspaces to specific monitors |
sweets.rule({ ... }) | Initial placement and behavior for matching XDG or XWayland windows |
sweets.env(...) | Export environment variables to launched commands |
sweets.exec_once(...) | Start a program once per Sweets session |
sweets.bind(...) | Key bindings, default bindings, and media keys |
sweets.bindswitch(...) | Commands for lid, tablet-mode, and keypad hardware switches |
| Mouse bindings | Built-in MOD + drag to move and resize windows |
sweets.include(...) | Load another Lua file, for splitting config across files |