NvChad: Guía Completa de Atajos, Comandos y Flujo de Trabajo Diario

La mayoría de los desarrolladores que prueban Neovim se atascan en el mismo lugar: pasan días configurando opciones, probando plugins, depurando init.lua, y nunca llegan a escribir código de verdad. NvChad resuelve ese problema dándote una configuración completa y cuidadosamente diseñada desde el primer día — árbol de archivos, statusline, buscador fuzzy con Telescope, soporte LSP, resaltado con Treesitter y un tema limpio — todo conectado y listo para usar.

Piensa en NvChad como la diferencia entre comprar muebles y construirlos tú mismo. Ambos terminan en un cuarto funcional, pero uno te tiene trabajando de inmediato y el otro es un proyecto de fines de semana que dura meses. NvChad son los muebles ensamblados. La idea no es que no puedas configurar Neovim desde cero — es que probablemente no deberías hacerlo hasta que sepas exactamente qué necesitas.

Esta guía cubre NvChad específicamente — no la configuración de Neovim vanilla. Al terminar conocerás cada atajo importante, cómo funciona el sistema de personalización, cómo añadir plugins y servidores LSP, y cómo mantener todo actualizado.

Qué Es NvChad (y Qué No Es)

NvChad es un framework de configuración de Neovim construido en Lua. Viene como un conjunto de plugins pre-configurados manejados por lazy.nvim, con un esquema de atajos consistente y una capa de UI personalizada. Obtienes un editor funcional inmediatamente después de la instalación.

Lo que NvChad no es:

Un plugin. No lo instalas dentro de una configuración existente de Neovim.
Una caja negra permanente. Todo es Lua legible; puedes rastrear cualquier comportamiento hasta su fuente.
Un reemplazo para principiantes que evita aprender los movimientos de Vim. Aún necesitas saber cómo moverte, seleccionar y editar en Neovim. NvChad añade herramientas encima, no en lugar de ellas.

La relación es: Neovim es el motor. NvChad es la carrocería.

Instalación

NvChad requiere Neovim 0.10 o posterior y una Nerd Font para los iconos. Instala ambos antes de continuar.

# en Arch / CachyOS
sudo pacman -S neovim
yay -S ttf-jetbrains-mono-nerd

# en Debian / Ubuntu
sudo apt install neovim
# instala una nerd font manualmente desde nerdfonts.com

# en macOS con Homebrew
brew install neovim
brew install --cask font-jetbrains-mono-nerd-font

Haz un respaldo de cualquier configuración existente de Neovim, luego clona NvChad:

# respaldar config existente si hay alguna
mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak

# clonar NvChad
git clone https://github.com/NvChad/starter ~/.config/nvim && nvim

En el primer arranque, lazy.nvim instala todos los plugins. Espera a que termine la instalación, luego reinicia Neovim. Ahora tienes un editor funcional.

La UI de NvChad

Antes de los atajos, entiende los componentes de UI con los que interactuarás diariamente.

Tabufline — la barra superior. Muestra los buffers abiertos (archivos), no pestañas en el sentido tradicional. Cada archivo abierto es un buffer. Cambias entre ellos, no cierras y vuelves a abrir archivos.

Statusline — la barra inferior. Muestra el modo actual (NORMAL / INSERT / VISUAL), rama de git, diagnósticos LSP, tipo de archivo, posición línea/columna y porcentaje de scroll.

NvimTree — el explorador de archivos a la izquierda. Actívalo con <C-n>. Soporta operaciones completas de archivos: crear, renombrar, eliminar, copiar, pegar.

NvDash — la pantalla de inicio que aparece cuando abres Neovim sin argumento de archivo. Navega con las flechas del teclado y Enter.

Cheatsheet — presiona <leader>ch en cualquier momento para abrir una ventana flotante con todos los atajos de NvChad organizados por categoría.

Entendiendo `<leader>`

Casi todos los atajos de NvChad usan <leader> como prefijo. En NvChad, <leader> está configurado como Space (barra espaciadora). Entonces cuando un atajo está escrito como <leader>ff, significa: presiona Space, luego f, luego f.

La tecla <leader> es un espacio de nombres. Todos los atajos personalizados viven bajo ella para evitar colisiones con los atajos nativos de Vim. Una vez que internalizas esto, todo el sistema de atajos se vuelve predecible.

Atajos Esenciales por Categoría

Archivos y Buffers

Atajo	Acción
`<C-n>`	Alternar explorador NvimTree
`<leader>e`	Enfocar NvimTree
`<Tab>`	Buffer siguiente
`<S-Tab>`	Buffer anterior
`<leader>x`	Cerrar buffer actual
`<leader>b`	Nuevo buffer

Los buffers en Neovim son persistentes. Cerrar un buffer con <leader>x no cierra la ventana — descarga el archivo. Para cerrar una división, usa :q o <C-w>q.

Divisiones de Ventana

Atajo	Acción
`<leader>h`	División horizontal
`<leader>v`	División vertical
`<C-h>`	Mover a ventana izquierda
`<C-l>`	Mover a ventana derecha
`<C-j>`	Mover a ventana inferior
`<C-k>`	Mover a ventana superior

La navegación entre ventanas usa <C-hjkl> — las mismas teclas de dirección que los movimientos de Vim, pero con Ctrl.

Telescope (Buscador Fuzzy)

Telescope es la herramienta más usada de NvChad para navegación. Busca fuzzy en archivos, buffers, texto, símbolos LSP y más.

Atajo	Acción
`<leader>ff`	Buscar archivos
`<leader>fg`	Live grep (buscar texto en el proyecto)
`<leader>fb`	Buffers abiertos
`<leader>fh`	Etiquetas de ayuda
`<leader>fo`	Archivos recientes
`<leader>fz`	Buscar en buffer actual
`<leader>cm`	Commits de git
`<leader>gt`	Estado de git
`<leader>pt`	Selector de colorscheme
`<leader>th`	Selector de tema NvChad

Dentro de cualquier buscador de Telescope:

<C-j> / <C-k> — mover arriba y abajo en la lista
Enter — abrir el seleccionado
<C-v> — abrir en división vertical
<C-x> — abrir en división horizontal
<C-t> — abrir en nueva pestaña
<Esc> — cerrar el buscador

Acciones LSP

Los atajos LSP están activos cuando un servidor LSP está adjunto al archivo actual. Proveen inteligencia a nivel IDE.

Atajo	Acción
`gd`	Ir a definición
`gD`	Ir a declaración
`gi`	Ir a implementación
`gr`	Mostrar referencias
`K`	Documentación hover
`<leader>sh`	Ayuda de firma
`<leader>ra`	Renombrar símbolo
`<leader>ca`	Acciones de código
`<leader>d`	Abrir diagnóstico flotante
`[d`	Diagnóstico anterior
`]d`	Diagnóstico siguiente
`<leader>fm`	Formatear archivo
`<leader>wa`	Añadir carpeta al workspace
`<leader>wr`	Eliminar carpeta del workspace

gd y gr son los más usados. Salta a la definición para entender el código, salta a las referencias para encontrar todos los usos.

Terminal

NvChad incluye un terminal toggle impulsado por el plugin nvterm.

Atajo	Acción
`<A-h>`	Alternar terminal horizontal
`<A-v>`	Alternar terminal vertical
`<A-i>`	Alternar terminal flotante

El terminal flotante es el más útil para comandos rápidos. Presiona <A-i>, ejecuta un comando, presiona <A-i> de nuevo para ocultarlo. La sesión del terminal persiste — no se reinicia cada vez que lo alternas.

Para salir del modo insert del terminal sin cerrarlo, presiona <C-x>.

Git Signs

gitsigns muestra los cambios de git en la columna de signos (la columna estrecha a la izquierda de los números de línea) y provee navegación por hunks.

Atajo	Acción
`]c`	Hunk siguiente
`[c`	Hunk anterior
`<leader>rh`	Resetear hunk
`<leader>ph`	Previsualizar hunk
`<leader>gb`	Git blame de línea
`<leader>td`	Alternar líneas eliminadas

Un “hunk” es un bloque contiguo de líneas cambiadas. <leader>ph muestra qué había antes del cambio en una ventana diff flotante.

Toggle de Comentarios

Atajo	Acción
`<leader>/`	Alternar comentario en línea actual
`<leader>/` (visual)	Alternar comentario en selección

Funciona con contexto de Treesitter — así que en un lenguaje embebido (TypeScript dentro de HTML, SQL dentro de cadenas Go) usa la sintaxis de comentario correcta.

Misceláneos

Atajo	Acción
`<leader>ch`	Cheatsheet de NvChad
`<Esc>`	Limpiar resaltados de búsqueda
`<leader>n`	Alternar números de línea
`<leader>rn`	Alternar números de línea relativos
`<leader>wK`	Mostrar todos los atajos
`<leader>ma`	Marcadores (Telescope marks)

Atajos de NvimTree

Cuando el foco está dentro de NvimTree, está activo un conjunto diferente de atajos.

Atajo	Acción
`Enter` o `o`	Abrir archivo o expandir carpeta
`a`	Crear nuevo archivo o carpeta (termina el nombre con `/` para carpeta)
`r`	Renombrar
`d`	Eliminar
`c`	Copiar
`x`	Cortar
`p`	Pegar
`y`	Copiar nombre de archivo
`Y`	Copiar ruta relativa
`gy`	Copiar ruta absoluta
`<C-v>`	Abrir en división vertical
`<C-x>`	Abrir en división horizontal
`H`	Alternar archivos ocultos
`I`	Alternar archivos ignorados por git
`R`	Refrescar árbol
`q`	Cerrar NvimTree

Crear un archivo: presiona a, escribe el nombre del archivo incluyendo cualquier ruta de subdirectorio. NvimTree crea los directorios que falten automáticamente. Para crear un directorio, termina el nombre con /.

Comandos de NvChad

Más allá de los atajos, varios comandos de Vim son específicos de NvChad o particularmente útiles.

:NvDash          " abrir el dashboard
:NvCheatsheet    " abrir el cheatsheet de atajos (igual que <leader>ch)
:Mason           " abrir la UI del gestor de paquetes Mason
:MasonInstallAll " instalar todos los servidores LSP listados en tu config
:MasonUpdate     " actualizar servidores instalados
:Lazy            " abrir la UI del gestor de plugins Lazy
:Lazy sync       " actualizar todos los plugins
:Lazy clean      " eliminar plugins no usados
:TSUpdate        " actualizar parsers de Treesitter
:TSInstall <lang>" instalar un parser de Treesitter para un lenguaje
:LspInfo         " mostrar servidores LSP activos para el buffer actual
:LspLog          " ver el log de depuración LSP
:checkhealth     " diagnosticar la salud de Neovim y los plugins

Ejecuta :checkhealth siempre que algo se comporte de manera inesperada. Verifica la versión de Neovim, proveedores de Python, Node.js, binarios externos y estado de plugins.

Configuración LSP: Añadiendo Servidores de Lenguaje

NvChad usa Mason para gestionar servidores LSP, formateadores y linters. Abre Mason con :Mason y navega por la lista. Presiona i para instalar un servidor.

Para una configuración más automatizada, declara los servidores que quieres en tu config personalizada. Crea el archivo ~/.config/nvim/lua/custom/configs/lspconfig.lua:

-- ~/.config/nvim/lua/custom/configs/lspconfig.lua
local on_attach = require("plugins.configs.lspconfig").on_attach
local capabilities = require("plugins.configs.lspconfig").capabilities

local lspconfig = require("lspconfig")

-- servidores que no necesitan configuración especial
local servers = { "html", "cssls", "ts_ls", "pyright", "bashls", "dockerls", "yamlls" }

for _, lsp in ipairs(servers) do
  lspconfig[lsp].setup({
    on_attach = on_attach,
    capabilities = capabilities,
  })
end

-- gopls necesita configuraciones específicas para Go
lspconfig.gopls.setup({
  on_attach = on_attach,
  capabilities = capabilities,
  settings = {
    gopls = {
      analyses = {
        unusedparams = true,
        shadow = true,
      },
      staticcheck = true,
      gofumpt = true,
    },
  },
})

-- rust_analyzer
lspconfig.rust_analyzer.setup({
  on_attach = on_attach,
  capabilities = capabilities,
  settings = {
    ["rust-analyzer"] = {
      checkOnSave = { command = "clippy" },
    },
  },
})

Luego instala los binarios correspondientes via Mason. Para Go:

:MasonInstallAll
" o individualmente:
:MasonInstall gopls gofumpt goimports golangci-lint-langserver

Después de instalar, vuelve a abrir el archivo y ejecuta :LspInfo para confirmar que el servidor se adjuntó.

Personalizando NvChad

NvChad separa su núcleo de tu config personal. Tus archivos personalizados viven en ~/.config/nvim/lua/custom/. Cuando actualizas NvChad, tu directorio custom/ nunca se toca.

El punto de entrada es ~/.config/nvim/lua/custom/chadrc.lua:

-- ~/.config/nvim/lua/custom/chadrc.lua
local M = {}

M.ui = {
  theme = "catppuccin",       -- tema por defecto
  theme_toggle = { "catppuccin", "one_light" },
  transparency = false,

  statusline = {
    theme = "default",        -- "default" | "vscode" | "vscode_colored" | "minimal"
    separator_style = "round", -- "default" | "round" | "block" | "arrow"
  },
}

M.plugins = "custom.plugins"  -- apunta a tu archivo de plugins

return M

Añadiendo Plugins

Crea ~/.config/nvim/lua/custom/plugins.lua:

-- ~/.config/nvim/lua/custom/plugins.lua
local plugins = {

  -- sobreescribir mason para instalar más servidores
  {
    "williamboman/mason.nvim",
    opts = {
      ensure_installed = {
        -- servidores LSP
        "gopls",
        "ts_ls",
        "pyright",
        "rust-analyzer",
        "lua-language-server",
        -- formateadores
        "gofumpt",
        "goimports",
        "prettier",
        "black",
        -- linters
        "golangci-lint",
        "eslint_d",
      },
    },
  },

  -- sobreescribir treesitter para instalar más parsers
  {
    "nvim-treesitter/nvim-treesitter",
    opts = {
      ensure_installed = {
        "go", "gomod", "gosum", "gowork",
        "typescript", "javascript", "tsx",
        "python", "rust", "lua",
        "sql", "yaml", "toml", "json",
        "dockerfile", "hcl",
        "markdown", "markdown_inline",
      },
    },
  },

  -- añadir un nuevo plugin que no está en el núcleo de NvChad
  {
    "folke/trouble.nvim",
    cmd = "Trouble",
    config = function()
      require("trouble").setup()
    end,
  },

  -- auto-cierre de paréntesis y comillas
  {
    "windwp/nvim-autopairs",
    event = "InsertEnter",
    config = function()
      require("nvim-autopairs").setup()
    end,
  },

  -- rodear objetos de texto
  {
    "kylechui/nvim-surround",
    event = "VeryLazy",
    config = function()
      require("nvim-surround").setup()
    end,
  },
}

return plugins

Después de guardar, abre Neovim y ejecuta :Lazy sync. Lazy instala los nuevos plugins y elimina los que ya no están en tu lista.

Añadiendo Atajos Personalizados

Crea ~/.config/nvim/lua/custom/mappings.lua:

-- ~/.config/nvim/lua/custom/mappings.lua
local M = {}

M.general = {
  n = {
    -- guardar archivo
    ["<C-s>"] = { "<cmd>w<CR>", "Guardar archivo" },

    -- salir
    ["<leader>q"] = { "<cmd>qa<CR>", "Salir de todo" },

    -- diagnósticos con trouble
    ["<leader>tt"] = { "<cmd>Trouble diagnostics toggle<CR>", "Diagnósticos Trouble" },

    -- formatear con LSP
    ["<leader>lf"] = {
      function()
        vim.lsp.buf.format({ async = true })
      end,
      "Formatear con LSP",
    },
  },

  i = {
    -- salir del modo insert más rápido
    ["jk"] = { "<Esc>", "Salir del modo insert" },
    ["kj"] = { "<Esc>", "Salir del modo insert" },
  },
}

return M

Referencia este archivo en chadrc.lua:

M.mappings = require("custom.mappings")

Temas y Apariencia

NvChad viene con más de 60 temas. Cámbialos interactivamente con <leader>th — un buscador de Telescope muestra una vista previa en vivo de cada tema mientras te mueves por la lista.

Los temas persisten entre sesiones. El tema elegido se guarda en ~/.local/share/nvim/nvchad_theme.

Para establecer un tema por defecto (que cargue inmediatamente al arrancar sin el selector), configúralo en chadrc.lua:

M.ui = {
  theme = "gruvchad",    -- cualquier nombre de tema del selector
}

Temas populares de NvChad:

catppuccin — suave, pastel, cómodo para sesiones largas
gruvchad — paleta marrón cálida, estética retro
onedark — colores familiares similares a VS Code
tokyonight — azules y morados fríos
nord — colores árticos desaturados

Actualizando NvChad

NvChad tiene tres mecanismos de actualización independientes: plugins, servidores LSP y parsers de Treesitter. Actualiza cada uno por separado.

" actualizar todos los plugins (lazy.nvim)
:Lazy sync

" actualizar servidores y herramientas gestionados por Mason
:MasonUpdate

" actualizar parsers de Treesitter
:TSUpdate

Después de :Lazy sync, Lazy muestra un resumen de qué se actualizó y si algo falló. Si una actualización de plugin rompe algo, puedes fijarlo a un commit anterior en tu custom/plugins.lua:

{
  "some/plugin",
  commit = "abc1234",   -- fijar a commit específico
},

Para actualizar la config base de NvChad (el repo starter):

cd ~/.config/nvim
git pull origin main

Tu directorio lua/custom/ está en el .gitignore del starter, así que las actualizaciones nunca tocan tus personalizaciones.

Patrones de Flujo de Trabajo Diario

Entender los atajos de forma aislada es menos útil que verlos en secuencia durante el trabajo real.

Abrir un Proyecto

nvim .                          # abrir NvimTree en el directorio actual
<leader>ff                      # encontrar un archivo por donde empezar
gd (sobre una llamada a función)# saltar a la definición
<Tab> / <S-Tab>                 # cambiar entre archivos abiertos

Buscar y Navegar

<leader>fg                      # live grep — encontrar una cadena en todo el proyecto
<C-j> / <C-k>                   # moverse entre resultados
Enter                           # abrir el archivo en la ubicación de la coincidencia
<leader>fb                      # cambiar a un buffer abierto específico

Trabajando con LSP

K                               # leer documentación del símbolo bajo el cursor
gd                              # saltar a la definición
gr                              # ver todos los usos del símbolo
<leader>ca                      # aplicar una acción de código (auto-import, fix, refactor)
<leader>ra                      # renombrar símbolo en todos los archivos
<leader>fm                      # formatear el archivo
[d / ]d                         # navegar entre errores y advertencias

Flujo de Git

<leader>gt                      # Telescope git status — ver archivos cambiados
]c / [c                         # saltar entre hunks cambiados
<leader>ph                      # previsualizar qué cambió en este hunk
<leader>gb                      # ver quién escribió la línea bajo el cursor (blame)

Ejecutar Código desde el Editor

<A-i>                           # abrir terminal flotante
go run ./cmd/api                # ejecutar tu proyecto
<A-i>                           # ocultar terminal (la sesión sigue activa)
<A-i>                           # recuperarla en cualquier momento

Solución de Problemas Comunes

Los iconos aparecen como cuadros o signos de interrogación. Tu terminal no está usando una Nerd Font. Configura la fuente en los ajustes de tu emulador de terminal.

LSP no se adjunta. Ejecuta :LspInfo — si el servidor no está listado, ejecuta :Mason e instálalo. Si está listado pero no se adjuntó, revisa :LspLog para ver errores.

Plugin no encontrado después de añadirlo. Ejecuta :Lazy sync después de editar custom/plugins.lua.

El resaltado de Treesitter se ve mal. Ejecuta :TSUpdate y reinicia Neovim.

Arranque lento. Ejecuta :Lazy profile para ver qué plugins tardan más en cargar. Añade lazy = true o mueve a event = "VeryLazy" los plugins no críticos.

Los resultados de Telescope están vacíos. Instala ripgrep para resultados de grep y fd para resultados de archivos:

# Arch / CachyOS
sudo pacman -S ripgrep fd

# Debian / Ubuntu
sudo apt install ripgrep fd-find

# macOS
brew install ripgrep fd

La diferencia entre un usuario de Neovim y uno que lo domina no es el número de plugins — es la profundidad de la familiaridad con las herramientas que ya están ahí. NvChad te da un conjunto completo desde el primer día. La inversión está en aprenderlo bien: internalizar los atajos hasta que no requieran ningún pensamiento, construir la memoria muscular para Telescope y la navegación LSP, y entender la capa de personalización lo suficientemente bien como para extender sin romper.

Un buen editor no te hace más rápido haciendo más por ti. Te hace más rápido desapareciendo — volviéndose invisible entre el pensamiento y el código.