Lua-based Hyprland plugin infrastructure share&discussion

[AbaoFromCUG]

I have been experimenting with a Lua-based plugin workflow for Hyprland.

hipe.hypr - the lua plugin manager of hyprland

The main piece is hipe.hypr, a small plugin manager inspired by lazy.nvim. It lets users describe Hyprland Lua plugins in a Lua spec, then handles cloning, local dev overrides, dependency ordering, package.path setup, config callbacks, keybind registration, optional LuaRocks dependencies, and even hyprpm plugins.

Example:

require("hipe").setup({
  spec = {
    "AbaoFromCUG/lua-plugin-template.hypr"，
    {
      "AbaoFromCUG/virtual-desktops.hypr",
      opts = { initial_count = 2 },
      keys = {
        { "SUPER + 1", function() require("virtual-desktops").vdesktop(1) end },
        { "SUPER + TAB", function() require("virtual-desktops").next_vdesktop() end },
      },
    },
  },
})

hipe.hypr support lua development workflow, support lsp settings, e.g. neovim:

vim.lsp.config("lua_ls", {
  settings = {
    Lua = {
      workspace = {
        library = vim.json.decode(vim.system({
          "hyprctl", "repl", 'return require("hipe").get_lsp_library()'
        }):wait().stdout),
      },
    },
  },
})

lua-plugin-template.hypr - a template project and starting point for lua plugin development

I also made lua-plugin-template.hypr as the recommended starting point for writing plugins managed by hipe. The convention is intentionally simple:

lua/plugin_name.lua        -- entry point, exports setup(user_config)
lua/plugin_name/*.lua      -- optional submodules
test/*_spec.lua            -- busted-style tests via hipe.test.runner

The template is meant to make a plugin feel like a normal Lua module: expose setup(), expose public functions for keybinds, keep implementation code in submodules, and test it with make test.

virtual-desktops.hypr a real practice of lua plugin

The first real plugin I am building on top of this is virtual-desktops.hypr, a lua-rewrite plugin of hyprland-virtual-desktops. virtual-desktops.hypr serves both as a useful plugin and as a test case for the workflow.

The goal is not to replace native Hyprland plugins. I want a lighter path for plugins where the native side stays small, while behavior, configuration, and user extension points can live in Lua.

Some feedback and suggestions(maybe)

I would like feedback on:

• whether this spec style feels natural for Hyprland users
• whether Hyprland could expose more Lua-native APIs, similar to the current set_workspace
• whether hyprctl repl could output ANSI escape sequences, which would make unit test output nicer with colors
• whether Hyprland could provide a native Lua entry point similar to nvim -l xxx.lua
• whether this should stay experimental or become a more formal plugin convention

If this direction makes sense, I would also be happy to work with the Hyprland maintainers on building the related ecosystem together.