NvChad로 NeoVim을 IDE처럼 꾸미기

NeoVim을 설치하고 기본적인 모달 편집에 익숙해졌는데, 막상 매일 쓰려니 뭔가 허전하지 않으셨나요? NeoVim 입문 가이드에서 다뤘듯이 플러그인을 하나씩 추가하면 IDE급 환경을 만들 수 있긴 한데, 그 “하나씩”이 문제입니다. 컬러 스킴 고르고, 상태바 설정하고, LSP 연결하고, 자동 완성 붙이고… 코딩은 안 하고 에디터 설정만 이틀째 하고 있는 자신을 발견하게 되죠. 😅

NvChad는 이 문제를 정면으로 해결합니다. 설치 한 줄이면 예쁜 UI에 빠른 시작 속도, 실용적인 플러그인 구성까지 한 번에 갖춰지거든요. 이 글에서는 NvChad가 뭔지, 어떻게 설치하고 자기 입맛대로 커스터마이징하는지까지 다뤄보겠습니다.

NvChad가 뭔가요?

NvChad는 NeoVim 위에 올리는 설정 프레임워크입니다. NeoVim 자체를 바꾸는 게 아니라, 미리 잘 짜인 Lua 설정과 플러그인 조합을 한 번에 적용해주는 거예요.

비슷한 도구로 LazyVim, AstroNvim, LunarVim 등이 있는데, 이런 것들을 통틀어 “NeoVim 배포판(distribution)“이라고 부릅니다. 각각 성격이 좀 다른데요.

LazyVim은 안정성과 생산성에 집중합니다. 군더더기 없이 실용적인 기본값을 제공하고, 작업 중심의 환경을 선호하는 분들에게 인기가 많아요. AstroNvim은 박스에서 꺼내자마자 바로 쓸 수 있는 완성도가 강점이고요. LunarVim은 한때 “올인원 IDE”를 표방하며 인기를 끌었지만, 최근에는 유지보수가 뜸해져서 새로 시작하는 분들에게 추천하기 어려운 상황입니다.

NvChad의 포지션은 좀 독특합니다. 코드베이스가 약 900줄 정도로 굉장히 가볍고, 68개 내장 테마에 자체 UI 플러그인까지 갖추고 있어서 보기에도 깔끔해요. “예쁘면서도 가벼운 NeoVim”을 원하는 분들이 주로 선택합니다.

설치 전 준비물

NvChad를 설치하기 전에 몇 가지를 먼저 챙겨야 합니다.

우선 NeoVim 0.11 이상이 필요합니다. macOS라면 brew install neovim으로 최신 버전을 설치할 수 있어요.

$ nvim --version

버전이 0.11 미만이라면 업데이트부터 해주세요.

다음으로 Nerd Font가 필요합니다. NvChad UI에는 파일 아이콘이나 상태바 심볼 같은 특수 문자가 쓰이는데, 일반 폰트에는 이 글리프가 없어서 깨져 보여요. JetBrainsMono Nerd Font 같은 걸 설치하고 터미널 폰트로 지정하면 됩니다.

$ brew install --cask font-jetbrains-mono-nerd-font

설치 후 사용하는 터미널(iTerm2, Alacritty, WezTerm 등)의 폰트 설정에서 “JetBrainsMono Nerd Font”를 선택하세요. 이때 이름 끝에 “Mono”가 붙지 않는 버전을 고르는 게 좋습니다. Mono 버전은 아이콘 글리프의 폭이 절반으로 줄어들어서 UI가 좀 어색해질 수 있거든요.

그리고 Ripgrep도 설치해두면 좋습니다. Telescope 플러그인의 텍스트 검색 기능이 ripgrep에 의존하거든요.

$ brew install ripgrep

마지막으로 tree-sitter CLI가 필요합니다. 구문 강조에 쓰이는 파서를 설치할 때 사용됩니다.

$ npm install -g tree-sitter-cli

설치하기

기존에 NeoVim 설정이 있다면 먼저 백업해두세요.

$ mv ~/.config/nvim ~/.config/nvim.backup

그다음 NvChad starter를 클론하고 NeoVim을 실행하면 끝입니다.

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

처음 실행하면 lazy.nvim이 필요한 플러그인을 자동으로 다운로드합니다. 잠시 기다리면 설치가 완료되고, 깔끔한 대시보드 화면이 나타나요.

설치가 끝나면 두 가지 명령어를 실행해서 나머지 도구도 설치해줍니다.

:MasonInstallAll
:TSInstallAll

:MasonInstallAll은 LSP 서버나 린터, 포매터 같은 외부 도구를 설치하고, :TSInstallAll은 Treesitter 파서를 설치합니다.

마지막으로 starter 저장소의 .git 폴더를 삭제합니다.

$ rm -rf ~/.config/nvim/.git

이제 이 디렉토리가 여러분만의 NeoVim 설정 저장소가 됩니다. 나중에 git init해서 본인의 dotfiles 저장소로 관리하면 되겠죠.

설정 파일 구조 이해하기

NvChad starter를 클론하면 이런 구조가 만들어집니다.

~/.config/nvim/
├── init.lua            # 진입점: lazy.nvim 부트스트랩
├── lua/
│   ├── chadrc.lua      # NvChad UI/테마 설정
│   ├── options.lua     # NeoVim 옵션 (줄 번호, 탭 크기 등)
│   ├── mappings.lua    # 커스텀 키 매핑
│   └── plugins/        # 플러그인 설정
│       └── init.lua
└── .stylua.toml        # Lua 코드 포매터 설정

핵심은 NvChad 본체가 이 디렉토리 안에 없다는 점입니다. NvChad는 lazy.nvim을 통해 플러그인처럼 설치되기 때문에 ~/.config/nvim에는 여러분의 설정만 들어있어요. NvChad 기본값 위에 여러분의 설정을 덮어씌우는 구조라서 수정하고 싶은 부분만 건드리면 됩니다.

init.lua는 lazy.nvim을 부트스트랩하고 NvChad를 플러그인으로 불러오는 역할입니다. 보통 이 파일은 건드릴 일이 없어요.

chadrc.lua가 NvChad 고유의 설정 파일입니다. 테마 변경, 상태바 스타일, UI 옵션 같은 NvChad 특화 설정을 여기서 합니다.

options.lua는 NeoVim 자체의 옵션을 설정하는 파일이고 mappings.lua는 키 매핑을 정의하는 파일입니다. NeoVim 입문 가이드에서 init.lua에 vim.opt와 vim.keymap.set을 직접 썼던 것과 같은 내용인데, 파일을 분리해서 관리하는 거예요.

테마 바꾸기

NvChad에서 가장 눈에 띄는 건 테마입니다. 68개 내장 테마가 있어서 별도 플러그인 없이도 다양한 색상 조합을 바로 써볼 수 있어요.

테마를 미리보려면 Space + th를 누르세요. Telescope 창이 뜨면서 테마 목록이 나타나고, 커서를 올리면 실시간으로 미리보기가 적용됩니다. 마음에 드는 테마를 선택하면 바로 반영되고요.

영구적으로 테마를 바꾸려면 chadrc.lua를 수정합니다.

---@type ChadrcConfig
local M = {}

M.base46 = {
  theme = "catppuccin",
}

return M

catppuccin, gruvbox, onedark, tokyonight 같은 익숙한 테마부터 everforest, rosepine 같은 세련된 테마까지 다양합니다. NvChad는 base46이라는 자체 테마 엔진을 쓰는데, 바이트코드로 컴파일해서 적용하기 때문에 테마 전환이 매우 빠릅니다.

자주 쓰는 단축키

NvChad는 Leader 키가 Space로 설정되어 있습니다. 주요 단축키를 카테고리별로 살펴볼게요.

파일을 찾을 때는 Space + ff로 파일명 검색, Space + fw로 파일 내용 검색(grep)을 할 수 있습니다. 열려 있는 버퍼 목록에서 찾으려면 Space + fb를 누르면 돼요. 이 세 가지가 Telescope 플러그인의 핵심 기능인데, 매일 수십 번씩 쓰게 될 겁니다.

버퍼(열린 파일) 사이를 이동할 때는 Tab으로 다음 버퍼, Shift + Tab으로 이전 버퍼로 갑니다. 특정 버퍼를 닫으려면 Space + x를 누르세요.

터미널은 Space + h로 수평 분할 터미널, Space + v로 수직 분할 터미널을 열 수 있습니다. 토글형이라서 다시 누르면 숨겨지고, 또 누르면 다시 나타나요. 에디터를 벗어나지 않고 빌드나 테스트를 돌릴 때 편리합니다.

파일 탐색기는 Space + e로 토글할 수 있고, Ctrl + n으로도 됩니다. nvim-tree 플러그인이 기본 탑재되어 있어서 VSCode의 사이드바와 비슷한 경험을 제공합니다.

단축키가 기억나지 않을 때는 Space + ch를 눌러보세요. NvChad의 치트시트가 뜨는데 모든 키 매핑이 카테고리별로 정리되어 있어서 한눈에 볼 수 있습니다. 메이슨리(masonry) 레이아웃으로 깔끔하게 배치되어 있고요.

LSP 설정하기

NvChad에는 mason.nvim과 nvim-lspconfig가 이미 포함되어 있어서 원하는 언어 서버만 추가하면 됩니다.

:Mason을 실행하면 설치 가능한 LSP 서버나 린터, 포매터 목록이 나타납니다. 여기서 필요한 걸 검색해서 i를 눌러 설치할 수 있어요.

설치한 LSP 서버를 NeoVim에 연결하려면 lua/plugins/init.lua에 lspconfig 설정을 추가합니다.

return {
  {
    "neovim/nvim-lspconfig",
    config = function()
      require("nvchad.configs.lspconfig").defaults()

      local lspconfig = require("lspconfig")
      local servers = { "ts_ls", "pyright", "rust_analyzer" }

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

require("nvchad.configs.lspconfig").defaults()가 NvChad의 기본 LSP 설정(키 매핑, 진단 표시 등)을 불러오고, 그 아래에서 원하는 서버를 추가하는 구조입니다.

LSP가 연결되면 gd로 정의로 이동하고, K로 문서 팝업을 띄우고, Space + ra로 이름을 바꾸고, Space + ca로 코드 액션을 쓸 수 있습니다. 자동 완성은 nvim-cmp 플러그인이 담당하는데, 이것도 NvChad에 기본 포함되어 있어서 LSP 서버만 연결하면 자동으로 동작해요.

플러그인 추가하기

NvChad는 lazy.nvim을 패키지 관리자로 쓰기 때문에 플러그인 추가도 lazy.nvim 문법을 따릅니다.

lua/plugins/init.lua에 원하는 플러그인을 추가하면 돼요. 예를 들어 Git 변경 사항을 줄 단위로 보여주는 gitsigns와 괄호/따옴표를 자동으로 닫아주는 autopairs는 이런 식으로 추가합니다.

return {
  {
    "lewis6991/gitsigns.nvim",
    event = "User FilePost",
    config = function()
      require("gitsigns").setup()
    end,
  },
  {
    "windwp/nvim-autopairs",
    event = "InsertEnter",
    config = function()
      require("nvim-autopairs").setup()
    end,
  },
}

여기서 event 필드가 중요합니다. "User FilePost"는 파일을 열었을 때, "InsertEnter"는 입력 모드에 진입했을 때 플러그인을 로드하겠다는 뜻이에요. 이렇게 지연 로딩(lazy loading)을 하면 NeoVim 시작 시에는 해당 플러그인이 메모리에 올라가지 않아서 시작 속도가 빠르게 유지됩니다.

NvChad가 빠른 이유의 93%가 이 지연 로딩 덕분이라고 공식 문서에서도 강조하고 있어요. 실제로 플러그인을 수십 개 설치해도 시작 시간이 0.02~0.07초 수준을 유지합니다.

설치한 플러그인을 동기화하려면 NeoVim에서 :Lazy sync를 실행하면 됩니다.

커스텀 키 매핑 추가하기

lua/mappings.lua 파일에서 키 매핑을 추가할 수 있습니다.

local map = vim.keymap.set

-- 파일 저장을 Ctrl+s로
map("n", "<C-s>", "<cmd>w<CR>", { desc = "Save file" })

-- ESC로 검색 하이라이트 끄기
map("n", "<Esc>", "<cmd>noh<CR>", { desc = "Clear highlights" })

-- 세미콜론으로 Command 모드 진입
map("n", ";", ":", { desc = "Enter command mode" })

NvChad의 기본 키 매핑 위에 추가되는 거라 충돌이 나지 않도록 신경 써주세요. desc 필드를 넣어두면 치트시트(Space + ch)에 설명이 함께 표시되어서 나중에 기억하기 편합니다.

Treesitter로 구문 강조 강화하기

NvChad에는 nvim-treesitter가 기본 포함되어 있습니다. Treesitter는 소스 코드를 AST(추상 구문 트리)로 파싱해서 정규식 기반 구문 강조보다 훨씬 정확한 색상 표시를 해줍니다.

기본적으로 lua 파서가 설치되어 있는데, 다른 언어 파서를 추가하려면 lua/plugins/init.lua에 이런 설정을 넣으면 됩니다.

{
  "nvim-treesitter/nvim-treesitter",
  opts = {
    ensure_installed = {
      "lua", "javascript", "typescript",
      "python", "rust", "html", "css",
      "json", "yaml", "markdown",
    },
  },
},

파서가 설치되면 해당 언어 파일을 열 때 구문 강조가 자동으로 적용됩니다. 함수명, 변수, 키워드, 문자열이 각각 다른 색상으로 구분되어서 코드 가독성이 크게 올라가요.

NvChad 업데이트와 제거

NvChad는 lazy.nvim으로 관리되니까 업데이트도 간단합니다.

:Lazy sync

이 명령어 하나로 NvChad 본체와 모든 플러그인이 최신 버전으로 업데이트됩니다.

혹시 NvChad가 마음에 안 들어서 제거하고 싶다면 설정 파일과 관련 데이터를 삭제하면 됩니다.

$ rm -rf ~/.config/nvim
$ rm -rf ~/.local/state/nvim
$ rm -rf ~/.local/share/nvim

삭제 후 NeoVim을 실행하면 플러그인 없는 순수 NeoVim으로 돌아갑니다. 아까 백업해둔 이전 설정이 있다면 ~/.config/nvim.backup을 다시 ~/.config/nvim으로 이름 바꿔주면 되고요.

kickstart.nvim과 뭐가 다른가요?

NeoVim 입문 가이드에서 kickstart.nvim을 언급했었는데, NvChad와는 성격이 꽤 다릅니다.

kickstart.nvim은 말 그대로 “출발점”입니다. 하나의 init.lua 파일에 기본적인 설정이 주석과 함께 들어있고, 직접 읽고 수정하면서 자기만의 설정을 만들어나가는 교육 목적이 강해요. NeoVim 설정의 구조를 이해하고 싶은 분들에게 적합합니다.

NvChad는 프레임워크에 가깝습니다. 기본 설정은 NvChad 저장소에 숨겨져 있고 덮어써야 할 부분만 건드리는 방식이에요. 내부 동작을 몰라도 바로 쓸 수 있는 대신 뭔가 바꾸고 싶을 때 NvChad의 구조를 따라야 하는 제약이 있습니다.

정리하면 이렇습니다. NeoVim의 작동 방식을 하나씩 이해하면서 설정을 쌓아가고 싶다면 kickstart.nvim이 낫고, 일단 예쁘고 빠른 환경에서 바로 코딩부터 시작하고 싶다면 NvChad가 낫습니다. 둘 다 써보고 결정해도 전혀 늦지 않아요.

마치며

NvChad는 NeoVim 설정의 진입 장벽을 확 낮춰주는 도구입니다. 68개 테마에 자체 UI 플러그인, 거기에 지연 로딩으로 최적화된 시작 속도까지. 설치하자마자 IDE 부럽지 않은 환경이 만들어지거든요. 코드베이스도 900줄 정도로 가벼워서 NvChad 소스를 읽어보면 Lua로 NeoVim 플러그인을 어떻게 구성하는지 배울 수도 있습니다.

NeoVim 자체가 처음이라면 먼저 Vim 완벽 가이드로 모달 편집의 기본기를 익히고, NeoVim 입문 가이드를 읽은 다음에 NvChad를 올리는 걸 추천합니다. 터미널 기반 개발 환경을 완성하고 싶다면 Zellij도 함께 살펴보세요. NvChad로 코드를 편집하면서 Zellij로 터미널을 분할해서 빌드나 테스트, Git 작업을 동시에 돌리면 마우스 없이도 쾌적한 개발 환경이 만들어져요.

더 자세한 내용은 NvChad 공식 문서와 NvChad GitHub 저장소를 참고하세요.