API Reference

May 16, 2026 ยท View on GitHub

This document covers the Lua API for programmatic access to leanpack.nvim.

Module Functions

leanpack.setup(opts)

Initialize leanpack.nvim with configuration.

Parameters:

  • opts (table): Configuration options

Returns: nil

require('leanpack').setup({
  cmd_prefix = 'leanpack',
  defaults = { confirm = true },
})

Plugin Management Commands

All plugin management operations are available as :Leanpack commands (not Lua API functions):

:Leanpack update              " Update all plugins
:Leanpack update plugin-name  " Update specific plugin
:Leanpack clean               " Remove unused plugins
:Leanpack sync                " Update + clean
:Leanpack build!              " Run all build hooks
:Leanpack load!               " Load all pending plugins

See Commands for full details.

State Functions

leanpack.state.get_all_entries()

Get all plugin entries.

Returns: table of plugin entries

local entries = require('leanpack.state').get_all_entries()
for src, entry in pairs(entries) do
  print(src, entry.load_status)
end

leanpack.state.get_entry(src)

Get specific plugin entry.

Parameters:

  • src (string): Plugin source

Returns: table or nil

local entry = require('leanpack.state').get_entry('nvim-treesitter/nvim-treesitter')

leanpack.state.is_configured()

Check if leanpack is configured.

Returns: boolean

if require('leanpack.state').is_configured() then
  -- leanpack is ready
end

Utility Functions

leanpack.spec.normalize_spec(spec)

Normalize a plugin spec.

Parameters:

  • spec (table): Plugin specification

Returns: table normalized spec

local normalized = require('leanpack.spec').normalize_spec({
  'user/repo',
  opts = {},
})

Hooks

Plugins can define hooks in their specs:

init(plugin)

Runs before plugin loads.

return {
  'user/repo',
  init = function(plugin)
    vim.g.plugin_loaded = true
  end,
}

config(plugin, opts)

Runs after plugin loads.

return {
  'user/repo',
  config = function(plugin, opts)
    require('plugin').setup(opts)
  end,
}

build(plugin)

Runs on install/update.

return {
  'user/repo',
  build = function(plugin)
    vim.fn.system({ 'make', '-C', plugin.path })
  end,
}

Types

Plugin Object

---@class leanpack.Plugin
---@field name string Plugin name
---@field path string Plugin directory path
---@field spec vim.pack.Spec The vim.pack spec

Spec Table

---@class leanpack.Spec
---@field [1] string Short name (user/repo)
---@field src? string Source URL or path
---@field dir? string Local directory
---@field url? string Git URL
---@field name? string Custom name
---@field dependencies? string|string[]|table Dependencies
---@field optional? boolean Optional dependency
---@field enabled? boolean|function Enable/disable
---@field cond? boolean|function Conditional loading
---@field lazy? boolean Force lazy loading
---@field priority? number Load priority
---@field dev? boolean Dev mode
---@field opts? table Setup options
---@field init? function Init hook
---@field config? function|boolean Config hook
---@field build? string|function Build hook
---@field event? string|string[]|table Event trigger
---@field cmd? string|string[] Command trigger
---@field keys? string|table|table[] Keymap trigger
---@field ft? string|string[] Filetype trigger
---@field version? string Version
---@field sem_version? string Semver (lazy.nvim compat)
---@field branch? string Branch
---@field tag? string Tag
---@field commit? string Commit
---@field main? string Main module

Next Steps