Basic Configuration

Put only the values you want to change in ~/.config/sweets/sweets.lua:

sweets.general({
    mod_key = "SUPER",
})

sweets.gaps({
    inner = 12,
    outer = 12,
    smart = true,
})

sweets.bind("MOD+D", "spawn", { "fuzzel" })

Load order

PREFIX follows the binary. /usr/bin/sweets reads /usr/share/sweets/sweets.lua, /usr/local/bin/sweets reads /usr/local/share/sweets/sweets.lua. XDG_CONFIG_HOME is honored when set.

With neither file present, Sweets starts with built-in defaults and a small set of emergency bindings.

How the layers combine

Your file does not replace the installed one wholesale. Each API merges differently:

A singleton such as sweets.general, sweets.layout, or sweets.gaps may be declared once per layer. Declaring one twice in the same layer, includes counted, is an error.

Validate

sweets --check-config              # installed and personal together
sweets --check-config ./test.lua   # one file on its own

A successful check prints the resolved path, then every evaluated source in order: installed defaults, their includes, your override, and its includes. If no file exists, it reports built-in defaults. An explicit path lists only that file and its includes. Syntax errors, unknown fields, wrong types, duplicate declarations, and unsafe include paths exit nonzero, list sources attempted so far, and name the failing source. Neither form opens a Wayland socket.

Reload

Sweets watches the installed file, your file, and every included file, and reloads on save. To reload manually, press MOD+Shift+R or run:

sweets msg reload

A reload is all or nothing. A rejected candidate leaves the last valid configuration active and shows the error on every monitor until you fix it.

Inspect the active path, generation, and latest error:

sweets msg config

Individual pages note when a valid reload affects only future actions or future windows.

X11 applications

XWayland is disabled by default. To run X11 applications, add this to your personal configuration and restart Sweets:

sweets.xwayland({ enabled = true })

X11 menus and tooltips keep their application-requested positions when reopened, including on mixed-scale monitors.

The sweets table

The global sweets table is the only API available to your configuration.

Unknown names and fields are rejected.

Strict globals

Reading an undeclared global rejects the configuration. This catches typos that Lua would otherwise turn into a silently absent field:

local enabled = true
sweets.pointer({ follow_focus = enabled })  -- valid

sweets.input({ natural_scroll = falsed })   -- error: unknown global `falsed`

Declare variables before reading them. An explicit nil still omits the entry as usual.

Sandbox

Lua functions, loops, tables, and the string, table, math, and utf8 libraries are available. Filesystem, process, and native-module access is not: io, os, package, require, debug, dofile, loadfile, load, pcall, xpcall, collectgarbage, and print are all removed.

Use sweets.include instead of require, and sweets.exec_once or a spawn binding to start programs. Commands are argument arrays and are never passed to a shell.

Each load is bounded:

Exceeding a limit rejects the configuration like any other error. Numbers must be finite; math.huge and 0/0 are rejected.

Next steps

• Split the configuration across files
• General settings for workspaces and focus
• Key bindings for actions and commands