Сборка плагина

Плагин Neovim — это всего лишь каталог в runtimepath. Традиционная структура включает каталоги верхнего уровня, которым Neovim назначает особое назначение.

Основные каталоги: lua/ для модулей, plugin/ для автоматически загружаемой настройки, ftplugin/ для скриптов типов файлов, doc/ для справки и after/ для поздних переопределений.

Файлы в каталоге lua/ доступны через require. Модуль в lua/myplugin/init.lua загружается как require('myplugin').

Вложенность соответствует точечным путям: lua/myplugin/config.lua превращается в require('myplugin.config'). Так плагины предоставляют аккуратное открытое пространство имён.

Идиоматичный шаблон модуля объявляет локальную таблицу M, добавляет в неё функции и возвращает её. Затем вызывающий код получает к ним доступ через require('myplugin').hello().

Храните внутренние вспомогательные функции как обычные локальные функции, чтобы открытой оставалась только предусмотренная поверхность модуля. Это соответствует инкапсуляции модулей в других экосистемах.

Большинство плагинов предоставляет функцию setup(opts). Она объединяет пользовательские параметры со значениями по умолчанию и выполняет инициализацию, например создаёт команды и автокоманды.

Используйте vim.tbl_deep_extend('force', defaults, opts or {}), чтобы даже частичная пользовательская конфигурация по-прежнему получала все значения по умолчанию.

Скрипты в plugin/ запускаются автоматически при старте Neovim, после построения runtimepath. Пусть они будут небольшими.

Обычно они регистрируют команды или защитный механизм, чтобы тяжёлые модули загружались отложенно. Избегайте здесь затратных операций: отложите их до setup или автокоманд, чтобы запуск оставался быстрым.

Защита от загрузки предотвращает повторную инициализацию, если файл подключается дважды. Установите флаг vim.g.loaded_* и немедленно выйдите при повторном входе.

Это необходимо, поскольку менеджеры плагинов и :runtime могут повторно подключать файлы, а дублирующиеся команды или автокоманды приводят к трудноуловимым ошибкам.

Быстрый запуск означает загрузку кода только тогда, когда он нужен. Зарегистрируйте лёгкую команду в plugin/, которая при первом использовании загрузит тяжёлый модуль через require.

Менеджеры плагинов, такие как lazy.nvim, формализуют этот подход с помощью триггеров cmd, ft и keys, поэтому модуль не затрагивается до вызова.

Neovim обнаруживает плагины, сканируя runtimepath. Встроенная система пакетов автоматически загружает каталоги в pack/*/start/, а каталоги в pack/*/opt/ — по запросу с помощью :packadd.

Большинство пользователей полагается на менеджер, но понимание runtimepath объясняет, как находятся Ваши каталоги.

Добавьте файл lua/myplugin/health.lua с функцией check, чтобы пользователи могли выполнить :checkhealth myplugin. Сообщайте о состоянии с помощью API vim.health.

Используйте vim.health.start, vim.health.ok, vim.health.warn и vim.health.error, чтобы чётко сообщать об отсутствующих зависимостях.

Добавьте справочный файл doc/myplugin.txt. Выполните :helptags doc/ (или поручите это менеджеру), чтобы создать индекс тегов и сделать доступной команду :help myplugin.

Хорошая документация содержит список команд, параметров setup и стандартных раскладок клавиш, благодаря чему Ваш плагин легко найти прямо из Neovim.

Разместите плагин в репозитории git; пользователи устанавливают его по пути owner/repo. Помечайте выпуски с использованием семантического версионирования, чтобы менеджеры могли закреплять версии.

Добавьте README с примерами установки для популярных менеджеров, лицензию и минимальный пример конфигурации, чтобы упростить начало работы с плагином.

Проверьте, насколько хорошо Вы поняли упаковку плагинов.

Плагин — это каталог в runtimepath с модулями в lua/, автоматически запускаемым скриптом в plugin/ и необязательными каталогами doc/, ftplugin/ и файлами проверки состояния.

Возвращайте таблицы модулей, предоставляйте setup, объединяющую значения по умолчанию, защищайтесь от повторной загрузки, загружайте тяжёлый код отложенно, документируйте плагин с помощью helptags и публикуйте его через git с тегами семантических версий.