Lua Academy · Lección

Empaquetar un plugin

Estructúrelo y compártalo

Empaquetar un plugin es una lección gratuita de Lua Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Lua Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Lua Academy incluye 4 lecciones en total.

Estructura de directorios de un plugin

Un plugin de Neovim no es más que un directorio incluido en runtimepath. La estructura convencional tiene carpetas de nivel superior que Neovim trata de forma especial.

Directorios principales: lua/ para los módulos, plugin/ para la configuración cargada automáticamente, ftplugin/ para los scripts de tipos de archivo, doc/ para la ayuda y after/ para las sobrescrituras tardías.

-- myplugin/
--   lua/myplugin/init.lua
--   plugin/myplugin.lua
--   doc/myplugin.txt

El directorio lua/

Puede acceder a los archivos de lua/ mediante require. Un módulo ubicado en lua/myplugin/init.lua se carga como require('myplugin').

El anidamiento se corresponde con rutas separadas por puntos: lua/myplugin/config.lua se convierte en require('myplugin.config'). Así es como los plugins exponen un espacio de nombres público y ordenado.

-- in lua/myplugin/init.lua
local M = {}
function M.hello() print('hi') end
return M

Devolver una tabla de módulo

El patrón idiomático para un módulo declara una tabla local M, le añade funciones y la devuelve. Después, los consumidores acceden a ella mediante require('myplugin').hello().

Mantenga los helpers internos como locales simples para que solo sea pública la interfaz prevista. Esto refleja la encapsulación de módulos de otros ecosistemas.

local M = {}
local function private() end
function M.run() private() end
return M

La convención setup()

La mayoría de los plugins exponen una función setup(opts). Esta combina las opciones del usuario con los valores predeterminados y realiza tareas de inicialización, como crear comandos y autocomandos.

Use vim.tbl_deep_extend('force', defaults, opts or {}) para que una configuración parcial del usuario siga recibiendo todos los valores predeterminados.

local M = {}
local defaults = { width = 40 }
function M.setup(opts)
  M.config = vim.tbl_deep_extend('force', defaults, opts or {})
end
return M

El directorio plugin/

Los scripts de plugin/ se ejecutan automáticamente cuando se inicia Neovim, después de construir runtimepath. Manténgalos pequeños.

Una tarea habitual es registrar comandos o una protección para que los módulos pesados se carguen de forma diferida. Evite realizar aquí tareas costosas; pospóngalas a setup o a los autocomandos para mantener un inicio rápido.

-- in plugin/myplugin.lua
if vim.g.loaded_myplugin then return end
vim.g.loaded_myplugin = true

Protecciones de carga

Una protección de carga evita la doble inicialización si el archivo se obtiene mediante source dos veces. Establezca un indicador vim.g.loaded_* y salga de inmediato si se vuelve a entrar.

Esto es esencial porque los gestores de plugins y :runtime pueden volver a obtener los archivos mediante source, y los comandos o autocomandos duplicados provocan errores sutiles.

if vim.g.loaded_myplugin == 1 then return end
vim.g.loaded_myplugin = 1

Carga diferida

Un inicio rápido implica cargar el código solo cuando sea necesario. Registre un comando ligero en plugin/ que requiera el módulo pesado la primera vez que se use.

Los gestores de plugins como lazy.nvim formalizan este proceso con los disparadores cmd, ft y keys, de modo que el módulo no se toca hasta que se invoca.

vim.api.nvim_create_user_command('MyStart', function()
  require('myplugin').run()
end, {})

runtimepath y packpath

Neovim descubre los plugins explorando runtimepath. El sistema de paquetes nativo carga automáticamente los directorios de pack/*/start/ y, bajo demanda mediante :packadd, los de pack/*/opt/.

La mayoría de los usuarios depende de un gestor, pero comprender runtimepath explica cómo se encuentran sus carpetas.

print(vim.o.runtimepath:sub(1, 60))
-- :packadd loads an opt plugin manually

Comprobaciones de estado

Proporcione un archivo lua/myplugin/health.lua con una función check para que los usuarios puedan ejecutar :checkhealth myplugin. Informe del estado mediante la API vim.health.

Use vim.health.start, vim.health.ok, vim.health.warn y vim.health.error para mostrar claramente las dependencias que faltan.

local M = {}
function M.check()
  vim.health.start('myplugin')
  vim.health.ok('all good')
end
return M

Documentación y etiquetas

Incluya un archivo de ayuda doc/myplugin.txt. Ejecute :helptags doc/ (o deje que lo haga el gestor) para generar el índice de etiquetas y permitir que funcione :help myplugin.

Una buena documentación enumera los comandos, las opciones de setup y los mapas de teclas predeterminados, lo que permite descubrir el plugin desde dentro de Neovim.

-- generate tags from the doc directory
vim.cmd('helptags ' .. vim.fn.expand('%:p:h'))

Versionado y publicación

Aloje el plugin en un repositorio de git; los usuarios lo instalan mediante la ruta owner/repo. Etiquete las versiones siguiendo el versionado semántico para que los gestores puedan fijarlas.

Incluya un README con fragmentos de instalación para los gestores más populares, una licencia y un ejemplo de configuración mínimo para facilitar su adopción.

-- lazy.nvim spec
-- { 'owner/myplugin', config = function()
--     require('myplugin').setup({})
--   end }

Comprobación rápida

Confirme que comprende cómo se empaquetan los plugins.

Repaso: empaquetar un plugin

Un plugin es un directorio de runtimepath con módulos en lua/, un script plugin/ que se ejecuta automáticamente y archivos opcionales en doc/, ftplugin/ y de comprobación de estado.

Devuelva tablas de módulo, exponga un setup que combine los valores predeterminados, evite las cargas duplicadas, cargue de forma diferida el código pesado, documente mediante helptags y publique en git con etiquetas de versión semánticas.

Preguntas frecuentes

¿La lección «Empaquetar un plugin» es gratis?

Sí — el texto completo de «Empaquetar un plugin» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Lua Academy, actualiza a CoddyKit PRO. El curso de Lua Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Empaquetar un plugin»?

Estructúrelo y compártalo Practicas Lua Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar Lua Academy?

No se requiere experiencia previa. Lua Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Empaquetar un plugin»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de Lua Academy?

Sí. Cada lección de Lua Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a Lua Academy