Gestor de plugins: lazy.nvim y vim.pack

Un plugin es solo código Lua que Neovim carga desde el runtimepath. Un gestor lo clona, lo actualiza y fija su versión. Desde 0.12 el editor trae el suyo —vim.pack— y lazy.nvim sigue siendo el rey de la carga perezosa. No compiten: la pregunta útil no es cuál eliges, sino qué plugin va en cada sitio. Empezamos instalando los dos por separado, y solo después los juntamos.

El falso dilema

Casi todo lo que leerás plantea esto como una elección excluyente: “¿lazy.nvim o vim.pack?”. Es una pregunta mal hecha. Los dos son gestores de Git con una capa de Lua encima, los dos dejan los plugins en directorios del runtimepath, y pueden convivir en la misma configuración.

La diferencia real está en la capa de arriba. vim.pack responde a “instala esto y mantenlo en esta versión”. lazy.nvim responde además a “…y no lo cargues hasta que pase tal cosa”, que es otro problema distinto. La mayor parte de una configuración no necesita esa segunda respuesta.

flowchart TD
I[init.lua] --> P[vim.pack]
I --> L[lazy.nvim]
P --> A[tema, treesitter, librerias]
L --> B[eventos, ft, cmd, teclas]
A --> R[runtimepath]
B --> R
style P fill:#a6e3a1,color:#11111b
style L fill:#cba6f7,color:#11111b
style R fill:#89b4fa,color:#11111b

La estructura de directorios

Antes de instalar nada, esto es lo que vas a construir. Vale para las dos vías:

~/.config/nvim/
├── init.lua                  <- el único archivo que Neovim lee solo
├── nvim-pack-lock.json       <- lo escribe vim.pack (va a Git)
├── lua/
│   ├── config/               <- tu configuración, cargada con require()
│   │   ├── options.lua
│   │   ├── keymaps.lua
│   │   ├── autocmds.lua
│   │   └── lazy.lua          <- solo si usas lazy.nvim
│   └── plugins/              <- solo si usas lazy.nvim: una spec por archivo
│       ├── colorscheme.lua
│       └── which-key.lua
└── lsp/                      <- servidores LSP (lección 2.1)

Todo lo que hay bajo lua/ es alcanzable con require: lua/config/options.lua se carga con require("config.options"). La carpeta lua/plugins/ no tiene nada de especial para Neovim; solo significa algo si le dices a lazy.nvim que la importe, y eso lo haremos explícito más abajo.

Instalar vim.pack

No hay nada que instalar: es una función del editor. No hay bootstrap, no hay clonado inicial, no hay if not fs_stat(...).

-- 1) El leader SIEMPRE antes que cualquier plugin
vim.g.mapleader = " "
vim.g.maplocalleader = " "

require("config.options")
require("config.keymaps")

-- 2) Los plugins
vim.pack.add({
  { src = "https://github.com/catppuccin/nvim", name = "catppuccin" },
  { src = "https://github.com/nvim-mini/mini.nvim" },
})

-- 3) Su configuración: el código ya se puede usar en la línea siguiente
require("catppuccin").setup({ flavour = "mocha" })
vim.cmd.colorscheme("catppuccin")
require("mini.surround").setup({
  -- Prefijo gs: nativamente "dormir N segundos", o sea libre.
  -- Deja s y S para flash.nvim (leccion 2.3).
  mappings = {
    add = "gsa", delete = "gsd", replace = "gsr",
    find = "gsf", find_left = "gsF", highlight = "gsh",
  },
})

Guarda, reinicia con :restart y ya está: los plugins que no estaban se clonan durante el add().

Una spec tiene tres claves:

Para version también vale vim.version.range("1.0"), que coge la mayor etiqueta semver del rango — pero solo funciona si el repositorio publica etiquetas del estilo v1.2.0; v1 o 1.2 no sirven.

Instalar lazy.nvim

lazy.nvim sí hay que instalarlo, y él no puede instalarse a sí mismo. Por eso toda config con lazy empieza con el mismo bloque: comprobar si está en disco y clonarlo si no.

-- 1) Bootstrap: clonar lazy.nvim la primera vez
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
  vim.fn.system({
    "git", "clone", "--filter=blob:none", "--branch=stable",
    "https://github.com/folke/lazy.nvim.git", lazypath,
  })
end

-- 2) Ponerlo al principio del runtimepath para poder hacer require
vim.opt.rtp:prepend(lazypath)

-- 3) Arrancarlo, diciéndole DÓNDE están tus specs
require("lazy").setup({
  spec = { { import = "plugins" } },   -- importa todo lua/plugins/*.lua
  checker = { enabled = true, notify = false },
  ui = { border = "rounded" },
})

Y en el init.lua, una sola línea:

vim.g.mapleader = " "
vim.g.maplocalleader = " "

require("config.options")
require("config.keymaps")

require("config.lazy")   -- a partir de aquí manda lazy

Una spec es un archivo que devuelve una tabla. El primer elemento es el repositorio, y el resto son opciones:

return {
  "folke/which-key.nvim",
  event = "VeryLazy",          -- cuándo cargarlo
  opts = { preset = "modern" }, -- lazy llama a setup(opts) por ti
}

Las cuatro claves de carga perezosa —las que justifican todo lazy.nvim— son:

Con :Lazy abres el panel para instalar, actualizar y revisar. :Lazy profile te dice qué plugin te está costando el arranque.

Dónde cae cada plugin

Ya tienes los dos montados. El criterio no es cuál te gusta más, sino si el plugin necesita no estar cargado.

En una config real la columna izquierda es casi siempre más larga. Y en 0.12 lo es todavía más, porque las piezas caras de antes —el LSP, el completado, el resaltado— ya no son plugins.

Tus tres primeros plugins

De aquí en adelante, cada instalación muestra las vías que tienen sentido para ese plugin. Cuando solo aparece una, el motivo está escrito.

El tema

return {
  "catppuccin/nvim",
  name = "catppuccin",
  priority = 1000,   -- antes que el resto
  lazy = false,      -- nunca diferido
  opts = { flavour = "mocha" },
  config = function(_, opts)
    require("catppuccin").setup(opts)
    vim.cmd.colorscheme("catppuccin")
  end,
}

vim.pack.add({
  { src = "https://github.com/catppuccin/nvim", name = "catppuccin" },
})

require("catppuccin").setup({ flavour = "mocha" })
vim.cmd.colorscheme("catppuccin")

Treesitter

El primero que no es cosmético. Instala los parsers que Neovim necesita para entender la estructura de tu código: el editor trae la librería de tree-sitter y las funciones que la usan, pero solo seis parsers de fábrica (C, Lua, Markdown, Vimscript, Vimdoc y el de las propias queries). Para Rust, Python o TypeScript no viene ninguno. Es la misma relación que con el LSP: Neovim pone el cliente, tú instalas los servidores. La lección 2.3 lo desarrolla.

vim.pack.add({
  { src = "https://github.com/nvim-treesitter/nvim-treesitter", version = "main" },
})

require("nvim-treesitter").install({
  "lua", "vim", "vimdoc", "c", "rust", "markdown",
})

Con los parsers en disco, el que enciende las funciones es Neovim. Un solo autocomando, sin listas que mantener a mano:

-- Sin esto, cada archivo se abre ENTERO PLEGADO y parece que has roto
-- el editor. Si te pasa alguna vez, zR lo abre todo. Lección 2.3.
vim.o.foldlevelstart = 99

vim.api.nvim_create_autocmd("FileType", {
  callback = function(args)
    -- ¿Hay parser para este tipo de archivo? Si no, no hacemos nada.
    local lang = vim.treesitter.language.get_lang(vim.bo[args.buf].filetype)
    if not lang or not vim.treesitter.language.add(lang) then return end

    vim.treesitter.start(args.buf, lang)                       -- resaltado
    vim.wo[0][0].foldexpr = "v:lua.vim.treesitter.foldexpr()"  -- plegado
    vim.wo[0][0].foldmethod = "expr"
  end,
})

Fíjate en que no hay ninguna lista de lenguajes: el autocomando pregunta si existe parser y actúa en consecuencia. Instala un parser nuevo y funciona solo, sin tocar esto. El plegado que acabas de encender se maneja con za para abrir y cerrar el de debajo del cursor, y zR para abrirlos todos; lo verás bien en la lección 2.3.

which-key

return {
  "folke/which-key.nvim",
  event = "VeryLazy",   -- tras el arranque, sin frenarlo
  opts = { preset = "modern" },
}

vim.pack.add({ { src = "https://github.com/folke/which-key.nvim" } })
require("which-key").setup({ preset = "modern" })

Reinicia, pulsa <leader> (espacio) y espera medio segundo: aparece el menú con los desc que escribiste en la lección anterior.

vim.api.nvim_create_autocmd("BufReadPre", {
  once = true,
  callback = function()
    vim.pack.add({ { src = "https://github.com/folke/which-key.nvim" } })
    require("which-key").setup({ preset = "modern" })
  end,
})

La configuración híbrida

Con los dos gestores entendidos por separado, juntarlos es directo. El nativo lleva el grueso; lazy entra solo para lo que gana con carga perezosa.

-- 1) Leader antes que nada
vim.g.mapleader = " "
vim.g.maplocalleader = " "

require("config.options")
require("config.keymaps")
require("config.autocmds")

-- 2) Lo que siempre está: gestor nativo
vim.pack.add({
  { src = "https://github.com/catppuccin/nvim", name = "catppuccin" },
  { src = "https://github.com/nvim-treesitter/nvim-treesitter", version = "main" },
  { src = "https://github.com/nvim-mini/mini.nvim" },
}, { load = true })

require("catppuccin").setup({ flavour = "mocha" })
vim.cmd.colorscheme("catppuccin")
require("nvim-treesitter").install({ "lua", "vim", "vimdoc", "c", "rust", "markdown" })
require("config.treesitter")
require("mini.surround").setup({
  -- Prefijo gs: nativamente "dormir N segundos", o sea libre.
  -- Deja s y S para flash.nvim (leccion 2.3).
  mappings = {
    add = "gsa", delete = "gsd", replace = "gsr",
    find = "gsf", find_left = "gsF", highlight = "gsh",
  },
})
require("mini.pairs").setup({})

-- 3) Lo que gana con carga perezosa: lazy.nvim
require("config.lazy")

Al lua/config/lazy.lua de antes solo hay que añadirle dos opciones:

require("lazy").setup({
  spec = { { import = "plugins" } },
  performance = {
    reset_packpath = false,   -- vim.pack necesita site en el packpath
    rtp = { reset = false },  -- y sus plugins ya están en el runtimepath
  },
  checker = { enabled = true, notify = false },
  ui = { border = "rounded" },
})

En lua/plugins/ dejas solo lo que de verdad se difiere: which-key con event, el depurador con cmd, los plugins por tipo de archivo con ft.

Qué pierdes y qué ganas

Referencia: el día a día de vim.pack

Esto no hace falta para empezar. Vuelve aquí cuando lo necesites.

El lockfile

vim.pack mantiene un lockfile en ~/.config/nvim/nvim-pack-lock.json, junto a tu init.lua, con la revisión exacta de cada plugin.

Actualizar

vim.pack.update()                          -- todos
vim.pack.update({ "mini.nvim" })           -- solo uno
vim.pack.update(nil, { offline = true })   -- mirar sin descargar

Abre un buffer de confirmación en una pestaña aparte con el changelog de cada plugin. :write aplica, :quit descarta. Dentro, ]] y [[ saltan entre plugins, K muestra el detalle de un cambio y gO lista la estructura. Después, :restart.

Cada actualización real queda en nvim-pack.log, en el directorio de logs de Neovim.

Volver atrás

git checkout HEAD -- nvim-pack-lock.json

-- tras :restart
vim.pack.update(nil, { offline = true, target = "lockfile" })

Ese target = "lockfile" es el equivalente exacto de :Lazy restore.

Borrar

Quita primero la spec del init.lua —si no, se reinstala en el siguiente arranque—, reinicia, y entonces:

vim.pack.del({ "which-key.nvim" })

Hooks de compilación

En lazy es una clave de la spec (build = ":TSUpdate"). Con vim.pack es un autocomando:

vim.api.nvim_create_autocmd("PackChanged", {
  callback = function(ev)
    -- kind es "install", "update" o "delete"
    if ev.data.spec.name == "un-plugin-con-make" and ev.data.kind ~= "delete" then
      vim.system({ "make" }, { cwd = ev.data.path })
    end
  end,
})

Diez líneas tuyas contra una clave de una tabla: exactamente el tipo de decisión que esta lección quiere que tomes con los ojos abiertos.

El flujo de trabajo