🧭 Telescope Lazy Plugins

🐧 Description

A Telescope picker to

quickly access configurations of plugins managed by

lazy.nvim.

📷 Screenshot

Example: Searching for telescope plugins configurations:

✨ Features

⚡ Simply search the plugin name and open its configuration at the corresponding file and line.

⚡ Quickly access all the specs where a plugin is defined.

⚡ No more head overload trying to remember in which file you changed that plugin option.

⚡ Easily find duplicates or conflicting overlapping settings.

⚡ Add custom entries to any file for your special needs.

⚡ Quickly execute builtin actions on the selected entry:

• Open the selected plugin configuration (<CR>).
• Open the selected plugin webpage in a browser (<C-g>x).
• Open the selected plugin README file (<C-g>r).
• Open the selected plugin repository local clone directory (<C-g>d).
• Open the selected plugin options passed into the plugin setup call (<C-g>c).
• Open a live_grep picker at the plugin's local directory path (<C-g>l).
• Open a find_files picker at the plugin's local directory path (<C-g>f).
• Create/Add your custom actions.

📌 Requirements

• Neovim >= v0.9.0
• lazy.nvim >= v11.0.0

📦 Installation

• Add it into the Telescope dependencies:

return {
  "nvim-telescope/telescope.nvim",
  dependencies = {
    { "polirritmico/telescope-lazy-plugins.nvim" },
  },
  -- etc.
}

Check the Configuration examples and the Configuration section for more details.

[!IMPORTANT]

📌 If your lazy configuration file is not located in the default path

(nvim/lua/config/lazy.lua), the lazy_config option must be set to a valid

path.

• Manually loading the extension:

require("telescope").loadextension("lazyplugins")

[!TIP]

It's recommended to run :checkhealth telescope after the installation (make

sure the extension is loaded first).

🔍 Usage

• Command-line:

:Telescope lazy_plugins

• Lua:

require("telescope").extensions.lazyplugins.lazyplugins()

🛠️ Configuration:

Add the options in the telescope.nvim opts extensions table inside lazy_plugins (configuration examples).

| Option | Type | Description | | --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | lazy_config | string | Path to the lua file containing the lazy.nvim plugins and/or opts passed to the require("lazy").setup(...) call. This is the first-level imported file and the one you would be directed by searching lazy.nvim. Should be set if the lazy.nvim config file path differs from the defaults. | | nameonly | boolean | Match only the repository name. Set to false to match the full account/reponame. | | show_disabled | boolean | Also show disabled plugins from the Lazy spec. | | auto_rescan | boolean | Automatically rescans and rebuilds the spec list if Lazy detects a change in the config (the rebuild occurs when the picker is reopened). | | ignore_imports | table | Array-like string table with modules to ignore. Useful for config distributions like LazyVim to avoid importing the inner configurations, e.g., { "lazyvim.plugins" }. | | picker_opts | table | Telescope layout options passed to the picker. Check :h telescope.layout. | | mappings | table | Keymaps attached to the picker. See :h telescope.mappings. Also, 'Custom Actions' could be added. | | livegrep | table | Custom options to be used by the livegrep picker action (<C-g>l). See :h telescope.builtin.live_grep. | | actions.opts_viewer | string | Where to open the selected plugin configuration options. Could be float or tab (defaults to float). | | custom_entries | table | A collection of custom entries to add into the picker. See the 'Custom Entries' section. |

⌨️ Mappings

In next table, the lp_actions column refers to the name of the action function provided by the module telescope-lazy-plugins.actions, accessible via:

require("telescope").extensions.lazy_plugins.actions

| Insert mode | Normal mode | lp_actions | Description | | ----------- | ----------- | ---------------------- | --------------------------------------------------------------------------------------------- | | <CR> | <CR> | open | Open the selected plugin config file at the first line of the plugin spec. | | <C-g>d | gd | openrepodir | Open the local clone folder of the plugin repository. | | <C-g>f | gf | openrepofindfiles | Open a Telescope findfiles picker at the repository local clone directory path. | | <C-g>l | gl | openrepolivegrep | Open a Telescope livegrep picker at the repository local clone directory path. | | <C-g>r | gr | open_readme | Open the selected plugin README file. | | <C-g>c | gc | openpluginopts | Open the selected plugin generated options from all spec fragments. | | <C-g>x | gx | openrepourl | Open the plugin repository url in the default web browser. | | <C-g>R | gR | rescan_plugins | Manually rescans the plugins config spec and rebuild the generated list. | | | | custom_action | A wrapper helper to use custom actions. See the 'Custom Actions' section. |

⚓ Defaults

---@class TelescopeLazyPluginsUserConfig
---@field lazy_config? string Path to the file containing the lazy opts and setup() call.
---@field mappings? table Keymaps attached to the picker. See :h telescope.mappings.
---@field nameonly? boolean Match only the reponame, false to match the full account/repo_name.
---@field picker_opts? table Layout options passed into Telescope. Check :h telescope.layout.
---@field show_disabled? boolean Also show disabled plugins from the Lazy spec.
---@field auto_rescan? boolean Automatic rescan and rebuild the spec list if Lazy detects a change in the config.
---@field custom_entries? (LazyPluginsCustomEntry|LazyPluginsData)[] Table to pass custom entries to the picker.
---@field livegrep? table Options to pass into the livegrep telescope builtin picker.
---@field ignore_imports? string[]|table<string, boolean> Array of imports to ignore.
---@field actions? LazyPluginsConfigActions Actions options.
---@class LazyPluginsConfigActions ---@field opts_viewer? LazyPluginsActionOptsViewer
---@alias LazyPluginsDataField --- | "name" Name of the plugin showed in the picker --- | "full_name" Full name of the plugin repository (account/repo) --- | "filepath" Full file path to the plugin lua configuration --- | "line" Line number of the plugin definition in the lua file --- | "repo_url" Url to the repo --- | "repo_dir" Path to the local repository clone --- | "file" Path to the config filename showed in the picker
---@alias LazyPluginsConfigViewer --- | "float" Default. Open the plugin config in a float window. --- | "tab" Open the plugin config in a new tab.

{
  lazy_config = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- This must be a valid path to the file containing the lazy opts and setup() call.
  nameonly = true, -- Match only the reponame, false to match the full account/repo_name.
  show_disabled = true, -- Also show disabled plugins from the Lazy spec.
  auto_rescan = true, -- Automatic rescan and rebuild the spec list if lazy detects a change in the config.
  custom_entries = {}, -- Table to pass custom entries to the picker.
  livegrep = {}, -- Options to pass into the livegrep telescope builtin picker.
  ignore_imports = {}, -- Add imports you want to ignore, e.g., "lazyvim.plugins".
  actions = {
    opts_viewer = "float", -- How to open the generated plugin options.
  },
  mappings = {
    ["i"] = {
      ["<C-g>d"] = lpactions.openrepo_dir,
      ["<C-g>f"] = lpactions.openrepofindfiles,
      ["<C-g>l"] = lpactions.openrepolivegrep,
      ["<C-g>c"] = lpactions.openplugin_opts,
      ["<C-g>r"] = lpactions.openplugin_readme,
      ["<C-g>x"] = lpactions.openrepo_url,
      ["<C-g>R"] = lpactions.rescanplugins,
    },
    ["n"] = {
      ["gd"] = lpactions.openrepo_dir,
      ["gf"] = lpactions.openrepofindfiles,
      ["gl"] = lpactions.openrepolivegrep,
      ["gc"] = lpactions.openplugin_opts,
      ["gr"] = lpactions.openplugin_readme,
      ["gx"] = lpactions.openrepo_url,
      ["gR"] = lpactions.rescanplugins,
    },
  },
  picker_opts = {
    sorting_strategy = "ascending",
    layout_strategy = "flex",
    layout_config = {
      flex = { flip_columns = 150 },
      horizontal = { preview_width = { 0.55, max = 100, min = 30 } },
      vertical = { previewcutoff = 20, previewheight = 0.5 },
    },
  },
}

⚙️ Configuration Examples:

🍚 Simple config:

{
  "nvim-telescope/telescope.nvim",
  cmd = "Telescope",
  dependencies = {
    { "nvim-lua/plenary.nvim" },
    {
      "polirritmico/telescope-lazy-plugins.nvim",
      keys = {
        { "<leader>cp", "<Cmd>Telescope lazy_plugins<CR>", desc = "Telescope: Plugins configurations" },
      },
    },
  },
  opts = {
    extensions = {
      ---@module "telescope.extensions.lazyplugins"
      ---@type TelescopeLazyPluginsUserConfig
      lazy_plugins = {
        lazy_config = vim.fn.stdpath("config") .. "/lua/lazy/init.lua", -- Must be a valid path to the file containing the lazy spec and setup() call.
      },
    },
    -- etc.
  },
}

💤 Lazy loading:

Lazy-loading Telescope extensions could be a little tricky. This approach creates a user auto command that checks when the telescope.nvim plugin is loaded and then executes the load_extension function (Could be used with any Telescope extension).

local loadextensionaftertelescopeisloaded = function(extensionname)
  local lazy_cfg = require("lazy.core.config").plugins
  if lazycfg["telescope.nvim"] and lazycfg["telescope.nvim"]._.loaded then
    -- Since Telescope is loaded, just load the extension:
    require("telescope").loadextension(extensionname)
  else
    -- If Telescope is not loaded, create an autocmd that will load the
    -- extension after Telescope is loaded.
    vim.api.nvimcreateautocmd("User", {
      pattern = "LazyLoad",
      callback = function(event)
        if event.data == "telescope.nvim" then
          require("telescope").loadextension(extensionname)
          return true
        end
      end,
    })
  end
end

return {
  {
    "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    dependencies = {
      { "nvim-lua/plenary.nvim" },
      {
        "polirritmico/telescope-lazy-plugins.nvim",
        init = function()
          loadextensionaftertelescopeisloaded("lazyplugins")
        end,
      },
    },
    keys = {
      {"<leader>cp", "<Cmd>Telescope lazy_plugins<CR>", desc = "Telescope: Plugins configurations"},
    },
    -- Add the plugin configuration through the Telescope extensions options:
    opts = {
      extensions = {
        ---@module "telescope.extensions.lazyplugins"
        ---@type TelescopeLazyPluginsUserConfig
        lazy_plugins = {
          show_disabled = true,
          lazy_config = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- path to the file containing the lazy opts and setup() call.
          -- This is not needed. It is just an example of how you can customize the picker layout. Check :h telescope.layout.
          picker_opts = {
            layout_strategy = "vertical",
            layout_config = {
              vertical = { previewcutoff = 15, previewheight = 0.5 },
            },
          },
          -- This is not needed. It is just an example of how you can add custom entries.
          custom_entries = {
            {
              name = "custom-entry-example",
              filepath = vim.fn.stdpath("config") .. "/lua/config/mappings.lua",
              repo_url = "https://www.lua.org/manual/5.2/",
              line = 23, -- Open the file with the cursor in this line
            },
          },
        },
      },
    },
  },
  -- etc.
}

📜 Full spec table

If your plugins are inside a large table passed directly to the require('lazy').setup({...}, opts) call, make sure to set the lazy_config option to specify the file where the spec table is defined. For example, for configurations in a single init.lua file:

-- Content of file: ~/.conf/nvim/init.lua
local opts = {
  -- Lazy configuration options
}
require("lazy").setup({
  -- full list of plugins and configs like this:
  "username/a_plugin",
  opts = {
    configurations = "custom values",
  },
  -- etc.
  {
    "nvim-telescope/telescope.nvim",
    dependencies = {
      { "nvim-lua/plenary.nvim" },
      { "polirritmico/telescope-lazy-plugins.nvim" },
    },
    opts = {
      extensions = {
        ---@module "telescope.extensions.lazyplugins"
        ---@type TelescopeLazyPluginsUserConfig
        lazy_plugins = {
          -- Set the path of this file (~/.config/nvim/init.lua) into the lazy_config field:
          lazy_config = vim.fn.stdpath("config") .. "/init.lua"
        },
      },
    },
  },
}, opts)

💻 Advanced Features

🔧 Custom Actions

The plugin also offer the possibility to add and define your custom actions to the picker through custom_action and helper functions.

Examples:

--- The example function
---@param bufnr integer passed by the telescope mapping execution call
---@param entry LazyPluginsData passed inside custom_action
---@param customargs {foo: string} If needed customargs could be added in a table
local function democustomfunction(bufnr, entry, custom_args)
  -- (require telescope inside the function call to not trigger a lazy load when
  -- parsing the config)
  local lpactions = require("telescope").extensions.lazyplugins.actions
local arguments = customargs.foo -- access values from the customargs   local repositorydir = entry.repodir -- access values from the selected picker entry   local message = string.format("%s%s", arguments, repository_dir)   vim.notify(message)
-- Use the provided helper builtin functions:   lpactions.appendtotelescopehistory(bufnr) -- Used by :Telescope resume and others.   lp_actions.close(bufnr) end -- etc.

--- Inside the lazy_plugins config
lazy_plugins = {
  mappings = {
    ["i"] = {
      ["<C-g>d"] = function(prompt_bufnr)
        local args = { foo = "Plugin path from the selected entry.repo_dir: " }
        require("telescope").extensions.lazyplugins.actions.customaction(
          prompt_bufnr,
          "repodir", -- This is used to validate the entry. Could be any field of LazyPluginsData (name, fullname, filepath, line, repourl or repodir).
          democustomfunction,
          args
        )
      end,
    },
  },
},

💈 Custom Entries

Custom entries could be added into the custom_entries field in the options. Should follow this specs:

---@class LazyPluginsCustomEntry
---@field name string Entry name
---@field filepath string Full path to the lua target file
---@field line? integer Optional: Line number to set the view on the target file. Defaults to 1.
---@field repourl? string Optional: URL to open with the openrepo_url action
---@field repodir? string Optional: Directory path to open with the openrepo_dir action

--- Custom entry example:
lazy_plugins = {
  custom_entries = {
    {
      name = "custom-entry",
      filepath = vim.fn.stdpath("config") .. "/lua/extra-options/somefile.lua",
      -- Optional:
      line = 42,
      repo_url = "https://www.lua.org/manual/5.2/",
      repo_dir = vim.fn.stdpath("config") .. "/lua/extra-options/",
    },
    -- etc.
  },
},

🎨 Highlights

This are the highlights defined by Telescope Lazy Plugins:

| Highlight group | Defaults to | Description | | ---------------------------- | ----------- | -------------------------------- | | TelescopeLazyPlugins | Normal | Plugin name | | TelescopeLazyPluginsFile | Comment | Module file with the config spec | | TelescopeLazyPluginsEnabled | Function | Enabled plugin icon | | TelescopeLazyPluginsDisabled | Delimiter | Disabled plugin icon |

🌱 Contributions

This plugin is made mainly for my personal use, but suggestions, issues, or pull requests are very welcome.

Enjoy