Hyprland Lua Migration Plan

Problem Statement

The Hyprland compositor config uses Home Manager's hyprlang output. Hyprland deprecates hyprlang for the main compositor config. The repository needs to generate a Lua config without changing desktop behavior.

Solution

Keep the config owned by Nix and Home Manager. Switch the Hyprland Home Manager config output to Lua. Convert only the settings whose shape changes under Lua.

This is not a desktop redesign. The change preserves the current monitors, binds, window rules, environment variables, and UWSM startup.

User Stories

As the operator, I want Hyprland to load hyprland.lua, so that startup no longer warns about hyprlang deprecation.
As the operator, I want existing keyboard binds to keep working, so that the desktop behavior stays unchanged.
As the operator, I want host monitor layout to stay unchanged, so that the physical display setup does not move.
As the operator, I want session environment variables to stay in the compositor config, so that Wayland and cursor behavior stays unchanged.
As the operator, I want auxiliary module binds to keep working, so that launcher, lock, screenshot, clipboard, notifications, and recording flows stay usable.

Implementation Decisions

Use Home Manager's Lua config generator. Set the Hyprland config type to Lua and keep package ownership unchanged.
Keep ordinary compositor options declarative in Nix. Move input, general, decoration, xwayland, animation, and layout settings into the Lua config structure.
Remove hyprlang-only variables from generated config. Keep modifier and terminal values as Nix locals or helper inputs.
Add minimal local helpers for Lua calls. Use helpers only for repeated bind, dispatcher, command, environment, and rule shapes.
Convert all bind strings to Lua bind call data. Preserve key combinations, dispatchers, commands, repeat behavior, and locked-session behavior.
Convert contributed binds in their owning modules. Keep each bind near the module that owns the tool it launches.
Convert monitor strings to Lua monitor records. Preserve output names, modes, positions, scale values, and rotation.
Convert the screenshot window rule to the Lua rule shape. Preserve the Satty class matcher and floating behavior.
Convert environment strings to Lua environment calls. Preserve the Wayland flag and cursor variables.
Delete or update comments that describe hyprlang syntax. Keep comments that explain behavior or non-obvious invariants.

Testing Decisions

Run the repository Nix formatting and style checks for modified Nix files.
Evaluate or build the affected host configuration. This proves Home Manager accepts the Lua settings structure.
Confirm the generated config file uses Lua. The expected output is hyprland.lua, not hyprland.conf.
Verify Hyprland accepts the generated Lua config. Use Hyprland config verification when the installed build supports it. Otherwise reload the compositor and inspect errors.
Smoke test the changed desktop surface. Test one bind from each source area after reload.
Check the explicit monitor layout on the host that declares it. Confirm resolution, position, scale, and rotation stayed unchanged.

Out of Scope

Do not split the config into Lua modules.
Do not hand-write a full Lua config.
Do not add new Hyprland behavior.
Do not change UWSM startup.
Do not redesign binds, monitor layout, or visual settings.
Do not change hyprlock, hypridle, waybar, mako, or rofi settings beyond their Hyprland binds.

Further Notes

Home Manager documents configType = "lua" for Hyprland. It maps settings to hl.* calls. It supports _args for multi-argument calls. It supports raw Lua expressions with lib.generators.mkLuaInline.

The riskiest parts are binds, monitor declarations, and window rules. Those parts changed shape more than scalar config sections.

Assumption: the pinned Home Manager input contains the documented Lua Hyprland generator. Validate this during the configuration build.

4.1 KiB Raw Blame History