Devlog

© 2020-2025 Heiker Curiel

Cómo crear tu primera configuración de Neovim usando lua

2022-07-02 | 19 minutos | Read in english
Última actualización: 2025-12-10

Aquí espero poder enseñarles suficiente sobre lua y la api de Neovim para poder construir una configuración que se adapte a sus necesidades.

Lo que haremos será crear un archivo de configuración que llamaremos init.lua, agregaremos un par de plugins y les diré cómo crear sus propios comandos.

Este tutorial está pensado para aquellos que son totalmente nuevos en Neovim. Si ya tienen una configuración escrita en vimscript y desean migrarla a lua, les recomiendo leer esto: Todo lo que necesitan saber para configurar neovim usando lua.

Recomendaciones

Antes de empezar, les aconsejo que instalen la versión estable de Neovim más reciente. Pueden visitar la sección releases del repositorio en github y descargarla de ahí. En esta ocasión necesitaremos una versión de Neovim que sea igual o mayor a v0.9.5.

Y si aún no se sienten cómodos usando Neovim para editar texto, hagan el tutorial interactivo que viene incluido. Pueden acceder a él ejecutando este comando en su terminal.

nvim +Tutor

El tutorial está inglés. Si no tienen un buen dominio del idioma pueden hacer el tutorial de Vim, que es un simple archivo de texto. Está disponible en repositorio de Vim: vim/runtime/tutor/tutor.es. Guardan ese archivo en algún lugar de su sistema y lo abren con Neovim. Voy a asumir que ya conocen todas las funcionalidades que enseña el tutor.

El Inicio

Lo primero que debemos hacer es crear nuestro archivo de configuración, el famoso init.lua. ¿Dónde? Depende de su sistema operativo y sus variables de entorno. Pero puedo enseñarles cómo crearlo desde Neovim, así no tenemos que preocuparnos por esos detalles.

Dato curioso: En algunos tutoriales se refieren al archivo de configuración como vimrc, porque ese es el nombre que tiene el archivo en Vim.

En esta sección no vamos a usar lua, usaremos el lenguaje que fue creado para Vim: vimscript.

Vamos a abrir Neovim y luego ejecutamos este comando.

:call mkdir(stdpath("config"), "p")

Con esto crearemos la carpeta donde vivirá nuestra configuración. Si quieren conocer la ubicación exacta usen este comando.

:echo stdpath("config")

Ahora vamos con el comando para editar la configuración.

:exe "edit" stdpath("config") . "/init.lua"

Después de ejecutarlo tendremos una "página" en blanco, pero el archivo aún no existe en el sistema. Para crearlo debemos guardarlo. Ejecuten esto.

:write

Una vez que tenemos el archivo podremos editarlo en cualquier momento con este comando.

:edit $MYVIMRC

Si ustedes son de aquellas personas que les gusta crear scripts para automatizar sus tareas, pueden ejecutar todos estos pasos con un sólo comando.

nvim --headless -c 'call mkdir(stdpath("config"), "p") | exe "edit" stdpath("config") . "/init.lua" | write | quit'

Opciones del editor

Para acceder a las opciones de Neovim debemos usar la variable global vim. Bueno, esto es más que una variable, es un módulo donde podemos encontrar cualquier tipo de utilidades. Pero ahora lo que nos interesa es una propiedad llamada o, con eso podremos modificar cualquiera de las 351 opciones que ofrece Neovim.

Esta es la sintaxis que deben seguir.

vim.o.nombre_opcion = valor

Donde nombre_opcion puede ser cualquiera de esta lista. Y valor debe concordar con el tipo de dato que espera la opción.

Pueden ver la lista de opciones desde Neovim con el comando :help option-list.

Deben tener en cuenta que cada opción tiene un "ámbito." Algunas opciones son globales, otras se limitan a la ventana o archivo que están manipulando en su momento. Para conocer estos detalles revisen la documentación de esta manera.

:help 'nombre_opcion'

Opciones de interés

Esta opción es de tipo booleano, quiere decir que sólo tiene dos posibles valores: true o false. Si le asignamos el valor true la habilitamos, false hace lo contrario.

Al habilitar number Neovim nos muestra los números de cada línea en pantalla.

vim.o.number = true

Con esto le decimos a Neovim si debe ignorar las letrás mayúsculas cuando realizamos una búsqueda. Por ejemplo, si buscamos la palabra dos nuestros resultados pueden incluir diferentes variaciones como Dos, DOS o dos.

vim.o.ignorecase = true

Hace que nuestra búsqueda ignore las letrás mayúsculas a menos que el término que estamos buscando tenga una letra mayúscula. Generalmente se usa en conjunto con ignorecase.

vim.o.smartcase = true

Resalta los resultados de una búsqueda anterior. La mayor parte del tiempo no queremos esto, así que lo deshabilitamos.

vim.o.hlsearch = false

Hace que el texto de las líneas largas (las que sobrepasan el ancho de la pantalla) siempre esté visible. Su valor defecto es true.

vim.o.wrap = true

Conserva la indentación de las líneas que sólo son visibles cuando wrap es true.

vim.o.breakindent = true

La cantidad de carácteres que ocupa Tab. El valor por defecto es 8. Yo prefiero 2.

vim.o.tabstop = 2

El espacio que Neovim usará para indentar una línea. Esta opción afecta los atajos << y >>. Su valor por defecto es 8. La convención es tener el mismo valor que tabstop.

vim.o.shiftwidth = 2

Determina si Neovim debe transformar el carácter Tab en espacios. Su valor por defecto es false.

vim.o.expandtab = false

En lo que se refiere a configuración de variables hay más características que podría mencionar, pero tenemos otras cosas qué hacer. Pueden encontrar más detalles del tema aquí: Configurando neovim - Opciones del editor.

Atajos de teclado

Para esto debemos aprender a usar la función vim.keymap.set. Les mostraré un ejemplo.

vim.keymap.set('n', '<space>w', '<cmd>write<cr>', {desc = 'Guardar'})

Después de ejecutar esta función la combinación Espacio + w nos permitirá usar el comando write. Podremos guardar el archivo actual con Espacio + w.

Ahora déjenme explicarles qué hace cada parámetro.

vim.keymap.set({mode}, {lhs}, {rhs}, {opts})

La tecla líder

Cuando definimos nuestros atajos podemos usar la secuencia especial <leader> en el parámetro {lhs}, esta toma el valor que tenemos en la variable global mapleader.

mapleader es una variable que debe ser una cadena texto. Por ejemplo.

vim.g.mapleader = ','

Con esto podríamos usar la tecla , como un prefijo para nuestros atajos.

vim.keymap.set('n', '<leader>w', '<cmd>write<cr>')

Y así la secuencia , + w guarda el archivo actual.

¿Qué pasa si no definimos mapleader? Por defecto tiene el valor \, que no es lo mejor del mundo. Mi recomendación para la tecla líder es usar Espacio. Pueden hacer esto.

vim.g.mapleader = ' '

Atajos

Ahora les mostraré algunos atajos que pueden ser útiles para ustedes.

Por defecto Neovim (y Vim) no interactúa con el portapapeles. Cuando copiamos algún texto con la tecla y el contenido se va un registro interno. Yo prefiero conservar esta funcionalidad y crear atajos dedicados para manipular el portapapeles.

Copia al portapapeles.

vim.keymap.set({'n', 'x'}, 'gy', '"+y')

Pegar desde el portapapeles.

vim.keymap.set({'n', 'x'}, 'gp', '"+p')

Cuando borramos algo en modo normal o visual usando c, d o x ese texto se va un registro. Esto afecta el texto que podemos pegar con la tecla p. Lo que quiero hacer es modificar x y X para poder borrar texto sin afectar el historial de copias.

vim.keymap.set({'n', 'x'}, 'x', '"_x')
vim.keymap.set({'n', 'x'}, 'X', '"_d')

Con estos atajos x puede borrar un caracter en modo normal, en modo visual va a borrar la selección actual. La X va a tener el mismo comportamiento del comando d.

vim.keymap.set('n', '<leader>a', ':keepjumps normal! ggVG<CR>')

Plugin manager

Aquí vamos a usar mini.nvim.

mini.nvim es una colección de módulos escritos en lua. Uno de esos módulos es el manejador de plugins que vamos a usar, mini.deps.

Deben saber el equipo de Neovim está trabajando en un manejador de plugins que estará en incluido en Neovim v0.12. Este manejador de plugins estará basado en mini.deps.

Ahora bien, ¿cómo se instala un plugin sin un manejador de plugins?

En Vim (y Neovim) es posible instalar un plugin si lo descargamos en una ubicación especial. El truco está en saber dónde. Lo que haremos será escribir una función (en lua) para descargar mini.nvim.

local mini = {}

mini.branch = 'main'
mini.packpath = vim.fn.stdpath('data') .. '/site'

function mini.require_deps()
  local uv = vim.uv or vim.loop
  local mini_path = mini.packpath .. '/pack/deps/start/mini.nvim'

  if not uv.fs_stat(mini_path) then
    print('Installing mini.nvim....')
    vim.fn.system({
      'git',
      'clone',
      '--filter=blob:none',
      'https://github.com/nvim-mini/mini.nvim',
      string.format('--branch=%s', mini.branch),
      mini_path
    })

    vim.cmd('packadd mini.nvim | helptags ALL')
  end

  local ok, deps = pcall(require, 'mini.deps')
  if not ok then
    return {}
  end

  return deps
end

Aquí tenemos una tabla de lua llamada mini, y esta contiene un par de opciones y una función.

La función .require_deps() usará el comando git clone para descargar mini.nvim si no se encuentra instalado en nuestro sistema. Luego intentará cargar el módulo mini.deps de manera segura. Ahora bien, este código simplemente crea la función. Para que tenga efecto debemos invocarla.

local MiniDeps = mini.require_deps()

if not MiniDeps.setup then
  return
end

Si todo sale bien la variable MiniDeps tendrá todas las funciones del módulo mini.deps. Si resulta que MiniDeps no contiene la función .setup debemos asumir que ocurrió algún error y se detiene la ejecución del script. De esta manera incluso si algo está mal el editor se mantendrá en un estado funcional.

En mini.nvim (casi) todos los módulos deben ser activados de manera explícita. Esto quiere decir que luego de usar la función require para cargar un módulo debemos ejecutar la función .setup().

MiniDeps.setup({
  path = {
    package = mini.packpath,
  },
})

La función .setup() es dónde colocamos nuestra configuración, si necesitamos una. En este caso no es estrictamente necesario. La variable mini.packpath ya contiene el valor que mini.deps espera por defecto. Pero si en algún momento necesitamos cambiar su valor debemos pasar esa información a mini.deps.

Ahora vamos a descargar un plugin, un tema para que el editor tenga una mejor apariencia. En este caso debemos usar la función .add().

MiniDeps.add('folke/tokyonight.nvim')

Esta es la cantidad mínima de información que mini.deps necesita para descargar un plugin de github. Basta con especificar el nombre del usuario (u organización) y el nombre del repositorio. Y curiosamente .add() funciona de manera similar a nuestra función .require_deps(), se asegura que el plugin esté instalado en nuestro sistema, de no ser así lo descarga, y finalmente lo añade al "runtimepath" de Neovim.

mini.deps también tiene el concepto de una "especificación," que en inglés lo llaman "plugin spec." En este contexto una especificación es simplemente una tabla de lua que debe tener ciertas propiedades. Así es cómo agregamos más información del plugin que queremos instalar. Podemos por ejemplo decir qué versión queremos instalar o qué rama debe usar para descargar actualizaciones. Este es un ejemplo:

MiniDeps.add({
  source = 'nvim-mini/mini.nvim',
  checkout = mini.branch,
})

Noten que reemplazamos la cadena de texto con una tabla de lua. La propiedad source es obligatoria, esta debe ser la URL del plugin. En este caso si sólo especificamos los últimos componentes mini.deps asume que el plugin está alojado en github. La propiedad checkout es donde le decimos qué versión queremos instalar, aquí podemos colocar el nombre de una rama, un tag, o un commit.

Vale la pena mencionar que ya instalamos mini.nvim en una ubicación donde mini.deps puede manejarlo. Añadir mini.nvim con MiniDeps.add() es opcional. A menos claro que quieran cambiar algo como la versión o la rama.

Ahora vamos a agregar el código para aplicar el nuevo tema para el editor.

vim.o.termguicolors = true
vim.cmd.colorscheme('tokyonight')

Aquí habilitamos la opción termguicolors de Neovim para asegurarnos de tener la "mejor versión" del tema. Cada tema puede tener dos versiones, una para terminales que sólo soportan 256 colores y otra que utiliza códigos en hexadecimal (tiene más variedad de colores).

Para decirle a Neovim qué tema queremos usamos el comando colorscheme. Okey... técnicamente estamos usando una función de lua, pero esa función esta ejecutando un comando de vim.

colorscheme tokyonight

Ahora guardamos los cambios y reiniciamos Neovim. Al abrir Neovim nuevamente deberá aparecer un mensaje que nos muestra que se está clonando el repositorio de mini.nvim. Una vez que termine el proceso de descarga entonces mini.deps empezará a instalar el resto de los plugins.

Configuración de plugins

Cada autor puede crear el método de configuración que mejor le parezca. ¿Cómo sabemos qué debemos hacer? Leemos la documentación, no nos queda de otra.

Cada plugin como mínimo debe tener un archivo llamado README.md. Este es el archivo que github nos muestra en la página principal del repositorio. Ahí debemos buscar las instrucciones de configuración.

Si el archivo README.md no tiene la información que nos interesa busquen una carpeta llamada doc. Por lo general ahí se encuentra un archivo txt, esa es la página de ayuda. Podemos leer ese archivo desde github o desde Neovim si usamos el comando :help nombre-archivo.

Convenciones de plugins escritos en lua

Por suerte para nosotros muchos de los plugins escritos en lua siguen un patrón, usan una función llamada .setup() que acepta una tabla de lua como argumento. Si hay algo que deben aprender para configurar plugins en lua es cómo crear tablas.

tokyonight.nvim, el tema que acabamos de descargar, es uno de esos plugins que tiene una función .setup(). Usaremos eso como ejemplo.

En el repositorio de tokyonight contiene una carpeta llamada doc y dentro está el archivo tokyonight.nvim.txt. Si desean leerlo desde Neovim usen este comando.

:help tokyonight.nvim.txt

Digamos que queremos deshabilitar las letras cursivas. En nuestra configuración debemos colocar algo como esto.

-- Ver :help tokyonight.nvim-tokyo-night-configuration
require('tokyonight').setup({
  styles = {
    comments = {italic = false},
    keywords = {italic = false},
  },
})

Deben tener en cuenta que esta función debe ser ejecutada antes de usar aplicar el tema.

¿Cómo sabe uno qué opciones tiene disponible un plugin? Leemos la documentación. Ahí pueden encontrar la sección tokyonight.nvim-tokyo-night-configuration. Ya cuando tienen una referencia de las opciones a la mano, deben conocer la sintaxis que deben usar para crear una tabla de lua. Lo otro que deben tener en cuenta es que cada plugin hará su mejor esfuerzo para mezclar las opciones que trae por defecto con nuestra configuración personal. Incluso si el plugin tiene muchas opciones sólo basta con especificar las opciones que nosotros queremos cambiar.

En este punto podemos guardar los cambios y usar al comando :source $MYVIMRC.

Vale la pena mencionar que invocar la función .setup() en tokyonight es opcional. No es como en mini.deps que debemos usarla para activar todas las funcionalidades del plugin. Aquí ya tenemos un ejemplo claro de que cada plugin tiene la libertad para hacer lo que quiera. No existe una regla o comportamiento fijo para la función .setup().

Plugins en vimscript

Aún hay muchos plugins útiles que están escritos en vimscript. En la mayoría de los casos los configuramos usando variables globales. En lua podremos modificar variables globales de vimscript usando vim.g.

¿Ya les conté que Neovim viene con un explorador de archivos? Podemos acceder a él con el comando :Lexplore. Este explorador es de hecho un plugin escrito en vimscript, aquí no tenemos una función .setup(). Para saber cómo configurarlo debemos buscar en la documentación.

:help netrw

Si revisan la tabla de contenido de esa página de ayuda notarán una sección llamada netrw-browser-settings. Ahí nos muestran una lista de variables y sus descripciones. Vamos a fijarnos en las que comienzan con el prefijo g:.

Por ejemplo, si queremos ocultar el texto de ayuda usamos netrw_banner.

vim.g.netrw_banner = 0

También podemos cambiar el tamaño de la ventana.

vim.g.netrw_winsize = 30

Eso es todo... bueno, hay más variables que pueden modificar pero en general esto es lo más básico que deben saber. Revisan la documentación, identifican la variable que quieren modificar y la cambian con vim.g.

Información extra

Atajos recursivos y no recursivos

Si ya conocen la palabra "recursividad" tal vez puedan intuir qué consecuencias tienen este tipo de atajos. Si no, dejénme demostrarles con un ejemplo.

Digamos que tenemos este atajo que abre el explorador de archivos.

vim.keymap.set('n', '<F2>', '<cmd>Lexplore<cr>')

Bien, ahora vamos a crear un atajo recursivo que utilice F2.

vim.keymap.set('n', '<space><space>', '<F2>', {remap = true})

Si pulsan Espacio dos veces seguidas les aparecerá el explorador. Pero si cambian remap de true a false no aparecerá nada.

Con los atajos recursivos podremos usar atajos definidos por nosotros mismos o por plugins. Con los atajos "no recursivos" sólo tendremos acceso a los atajos definidos directamente por Neovim.

Por lo general sólo queremos atajos recursivos cuando vamos a usar funcionalidades creadas por plugins.

¿Por qué los atajos recursivos pueden causar conflictos? Consideren esto.

vim.keymap.set('n', '*', '*zz')

Noten que estamos usando * en {lhs} y también en {rhs}. Si este atajo fuera recursivo estaríamos creando un ciclo infinito. Neovim intentará llamar a la funcionalidad atada a * y nunca ejecuta zz.

Comandos de usuario

Para crear nuestros propios comandos usamos esta función:

vim.api.nvim_create_user_command({name}, {command}, {opts})

Ejemplo, podemos crear un comando dedicado para recargar nuestra configuración.

vim.api.nvim_create_user_command('ReloadConfig', 'source $MYVIMRC', {})

Si quieren saber más detalles de los comandos de usuario revisen la documentación con los comandos.

:help nvim_create_user_command()
:help user-commands

Autocomandos

Los autocomandos son acciones que Neovim puede ejecutar cuando ocurre un evento. Pueden revisar la lista de eventos con el comando :help events.

Podemos crear un autocomando con esta función.

vim.api.nvim_create_autocmd({event}, {opts})

Aquí les va un ejemplo. Voy a crear un grupo llamado user_cmds y le agregaré dos autocomandos.

local augroup = vim.api.nvim_create_augroup('user_cmds', {clear = true})

vim.api.nvim_create_autocmd('FileType', {
  pattern = {'help', 'man'},
  group = augroup,
  desc = 'Usar q para cerrar ventana',
  command = 'nnoremap <buffer> q <cmd>quit<cr>'
})

vim.api.nvim_create_autocmd('TextYankPost', {
  group = augroup,
  desc = 'Resaltar texto copiado',
  callback = function(event)
    vim.highlight.on_yank({higroup = 'Visual', timeout = 200})
  end
})

Crear el grupo es opcional.

El primer autocomando creará el atajo q para cerrar la ventana actual, pero sólo si el archivo actual es de tipo help o man. En este ejemplo estoy usando vimscript en la propiedad command, pero también pude haberlo hecho usando lua con la propiedad callback.

El segundo autocomando usa una función de lua en la propiedad callback. Esta función lo que hace es resaltar el texto que copiamos. Pueden probar su efecto si copian una línea usando el atajo yy.

Para conocer más detalles de los autocomandos revisen la documentación.

:help autocmd-intro

Módulos de usuario

No hay ninguna regla que nos obligue a tener toda nuestra configuración en un solo archivo. Podemos crear módulos para separar la configuración en piezas más pequeñas.

La convención es colocar todos nuestros módulos en un "espacio único" para evitar conflictos con plugins. Muchas personas crean un módulo llamado user (ustedes pueden darle otro nombre si quieren). Para esto debemos ir la carpeta donde está init.lua, crear el directorio lua, y dentro creamos user. Podemos hacer todo eso con un comando.

:call mkdir(stdpath("config") . "/lua/user", "p")

Ya dentro de /lua/user podemos crear nuestros scripts de lua. Vamos a suponer que tenemos uno llamado settings.lua. Ahora, Neovim no sabe que ese script existe, no lo va a ejecutar, nosotros debemos llamarlo desde init.lua así.

require('user.settings')

Si quieren saber con detalle cómo funciona require... revisen la documentación.

:help lua-require

La función require

Algo que deben saber de require es que sólo ejecuta el módulo una vez. ¿Qué quiere decir esto?

Consideren este código.

require('user.settings')
require('user.settings')

Aquí el script settings.lua sólo se ejecutará una vez. Si desean crear plugins o alguna funcionalidad que depende de un plugin, esto es bueno. Lo malo es que si quieren usar el comando :source $MYVIMRC para "recargar" su configuración no obtendrán el resultado que quieren.

Hay un truco que pueden hacer. Pueden invalidar el caché de la función require antes de invocarla con un módulo. Ejemplo.

local load = function(mod)
  package.loaded[mod] = nil
  require(mod)
end

load('user.settings')
load('user.keymaps')

Sí hacemos esto en init.lua el comando source podrá ejecutar los módulos settings y keymaps de manera efectiva.

ADVERTENCIA. Deben tener en cuenta que algunos plugins pueden actuar de manera extraña si los configuran más de una vez. Es decir, si ustedes usan :source $MYVIMRC y provocan que la función .setup() de un plugin se ejecute por segunda vez puede causar efectos inesperados.

init.lua

Entonces, si aplican (casi) todo lo que les enseñé hoy este sería el resultado.

¿Qué sigue?

El siguiente paso es crear un ambiente de desarrollo en el que se sientan productivos. Investiguen qué plugins utiliza la comunidad de Neovim.

Este paso puede ser difícil si no saben dónde empezar, por eso he creado una "plantilla" que pueden revisar o incluso usar como base para su propia configuración personal.

Conclusión

Ahora sabemos cómo modificar las opciones básicas de Neovim. Aprendimos cómo crear nuestros propios atajos. Podemos hacer que Neovim descargue plugins desde github. Configuramos un par de plugins, uno escrito en lua, otro escrito en vimscript. Dimos un vistazo a temas como atajos recursivos, comandos de usuario, autocomandos, módulos y algunos trucos.

En este punto ya tenemos todas la herramientas para explorar plugins, ver las configuraciones de otras personas y aprender de ellas.

¿Tienen alguna pregunta? Pueden dejar un comentario en cualquiera de estas plataformas:

Pueden contactarme por las redes sociales:

Gracias por su tiempo. Si este artículo les pareció útil y quieren apoyar mis esfuerzos para crear más contenido, pueden dejar una propina en buy me a coffee ☕.

Buy Me A Coffee