Lua Academy · Aula

Empacotando um plugin

Estruture e compartilhe-o.

Empacotando um plugin é uma aula grátis de Lua Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Lua Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Lua Academy inclui 4 aulas no total.

Estrutura de diretórios de plug-ins

Um plug-in do Neovim é apenas um diretório no runtimepath. A estrutura convencional tem pastas de nível superior que o Neovim trata de maneira especial.

Diretórios principais: lua/ para módulos, plugin/ para configurações carregadas automaticamente, ftplugin/ para scripts de tipos de arquivo, doc/ para ajuda e after/ para substituições tardias.

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

O diretório lua/

Os arquivos em lua/ podem ser acessados com require. Um módulo em lua/myplugin/init.lua é carregado como require('myplugin').

O aninhamento corresponde a caminhos separados por pontos: lua/myplugin/config.lua torna-se require('myplugin.config'). É assim que os plug-ins oferecem um espaço de nomes público e organizado.

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

Retornando uma tabela de módulo

O padrão idiomático de módulo declara uma tabela local M, associa funções a ela e a retorna. Os chamadores podem então acessar require('myplugin').hello().

Mantenha os auxiliares internos como variáveis locais simples para que apenas a interface pretendida seja pública. Isso reflete o encapsulamento de módulos presente em outros ecossistemas.

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

A convenção setup()

A maioria dos plug-ins oferece uma função setup(opts). Ela mescla as opções do usuário com os valores padrão, dando prioridade às primeiras, e realiza inicializações como a criação de comandos e comandos automáticos.

Use vim.tbl_deep_extend('force', defaults, opts or {}) para que uma configuração parcial do usuário ainda receba todos os valores padrão.

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

O diretório plugin/

Os scripts em plugin/ são executados automaticamente quando o Neovim é iniciado, depois que o runtimepath é construído. Mantenha-os pequenos.

Uma tarefa comum é registrar comandos ou uma proteção para que módulos pesados sejam carregados sob demanda. Evite trabalhos dispendiosos aqui; adie-os para setup ou para comandos automáticos, mantendo a inicialização rápida.

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

Proteções de carregamento

Uma proteção de carregamento evita a inicialização duplicada caso o arquivo seja carregado duas vezes. Defina um sinalizador vim.g.loaded_* e interrompa o processamento logo no início quando houver uma nova entrada.

Isso é essencial porque os gerenciadores de plug-ins e :runtime podem carregar os arquivos novamente, e comandos ou comandos automáticos duplicados causam erros sutis.

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

Carregamento sob demanda

Uma inicialização rápida significa carregar o código apenas quando necessário. Registre um comando leve em plugin/ que exija o módulo pesado na primeira utilização.

Gerenciadores de plug-ins como lazy.nvim formalizam isso com os gatilhos cmd, ft e keys, para que seu módulo só seja acessado quando for invocado.

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

Caminho de execução e caminho de pacotes

O Neovim descobre os plug-ins verificando o runtimepath. O sistema nativo de pacotes carrega automaticamente os diretórios em pack/*/start/ e, sob demanda, os diretórios em pack/*/opt/ por meio de :packadd.

A maioria dos usuários depende de um gerenciador, mas entender o runtimepath explica como suas pastas são encontradas.

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

Verificações de integridade

Forneça um arquivo lua/myplugin/health.lua com uma função check para que os usuários possam executar :checkhealth myplugin. Relate o estado usando a API vim.health.

Use vim.health.start, vim.health.ok, vim.health.warn e vim.health.error para indicar claramente as dependências ausentes.

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

Documentação e marcadores

Inclua um arquivo de ajuda doc/myplugin.txt. Execute :helptags doc/ — ou deixe o gerenciador fazer isso — para gerar o índice de marcadores, permitindo que :help myplugin funcione.

Uma boa documentação lista os comandos, as opções de setup e os mapas de teclas padrão, tornando seu plug-in fácil de descobrir dentro do Neovim.

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

Versionamento e publicação

Hospede o plug-in em um repositório git; os usuários o instalam usando o caminho owner/repo. Marque as versões seguindo o versionamento semântico para que os gerenciadores possam fixá-las.

Inclua um README com trechos de instalação para gerenciadores populares, uma licença e um exemplo mínimo de configuração para facilitar a adoção.

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

Verificação rápida

Confirme sua compreensão sobre o empacotamento de plug-ins.

Recapitulação: empacotando um plug-in

Um plug-in é um diretório do runtimepath com módulos em lua/, um script plugin/ executado automaticamente e arquivos opcionais em doc/, ftplugin/ e de integridade.

Retorne tabelas de módulo, exponha uma função setup que mescle os valores padrão, evite carregamentos duplicados, carregue códigos pesados sob demanda, documente com marcadores de ajuda e publique por meio do git usando marcadores de versão semântica.

Perguntas Frequentes

A aula “Empacotando um plugin” é grátis?

Sim — o texto completo de “Empacotando um plugin” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Lua Academy, atualize para CoddyKit PRO. O curso de Lua Academy inclui 4 aulas no total.

O que vou aprender em “Empacotando um plugin”?

Estruture e compartilhe-o. Você pratica Lua Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Lua Academy?

Nenhuma experiência prévia é necessária. Lua Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.

Quanto tempo leva a aula “Empacotando um plugin”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Lua Academy?

Sim. Cada aula de Lua Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Lua Academy