mirror
/
kickstart.nvim
mirror of https://github.com/nvim-lua/kickstart.nvim.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity
kickstart.nvim/INSTALLATION.md

12 KiB
Raw Blame History

Complete Installation Guide - Neovim Profile Setup

This guide documents all the tools and setup steps needed to replicate this VS Code-like Neovim configuration on a new computer.

📋 Prerequisites

Required Software

  • macOS (this guide is for macOS, adapt for Linux/Windows)
  • Homebrew - Package manager for macOS
  • Neovim v0.10+ - Text editor
  • Git - Version control

🛠️ Installation Steps

1. Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Neovim

brew install neovim

Verify installation:

nvim --version
# Should show v0.10.0 or higher

3. Install Node.js via fnm (Fast Node Manager)

Why fnm?

  • Fast and simple Node.js version manager
  • Written in Rust (very fast)
  • Better than nvm for switching Node.js versions
  • Required for GitHub Copilot and some LSP servers

Install fnm

brew install fnm

Configure fnm in your shell

Add to ~/.zshrc:

# fnm (Fast Node Manager) - for managing Node.js versions
eval "$(fnm env --use-on-cd)"

Reload your shell:

source ~/.zshrc

Install Node.js LTS

# Install latest LTS version
fnm install --lts

# Set it as default
fnm default lts-latest

# Verify installation
node --version
# Should show v24.x.x or similar

npm --version
# Should show 11.x.x or similar

fnm Directory Structure

fnm stores Node.js versions here:

  • Versions: ~/.local/share/fnm/node-versions/
  • Default alias: ~/.local/share/fnm/aliases/default/bin/

The default alias automatically points to your default Node.js version, so you don't need to update paths when upgrading Node.js.

4. Install Bun (Fast JavaScript Runtime)

Why Bun?

  • Faster than Node.js for development
  • Great for running Svelte/TypeScript projects
  • Built-in bundler and test runner
  • Compatible with Node.js packages

Install Bun

curl -fsSL https://bun.sh/install | bash

This installs Bun to ~/.bun/bin/bun

Configure Bun in your shell

Add to ~/.zshrc (should be added automatically, but verify):

# Bun - Fast JavaScript runtime
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Reload your shell:

source ~/.zshrc

Verify installation:

bun --version
# Should show 1.3.x or similar

5. Clone Kickstart.nvim Configuration

Backup existing config (if you have one)

mv ~/.config/nvim ~/.config/nvim.backup
mv ~/.local/share/nvim ~/.local/share/nvim.backup
mv ~/.local/state/nvim ~/.local/state/nvim.backup

Clone Kickstart.nvim

git clone https://github.com/nvim-lua/kickstart.nvim.git ~/.config/nvim

6. Apply Custom Profile Configuration

You need to copy these custom files to your new machine:

Required Custom Files

~/.config/nvim/
├── init.lua (modified from kickstart)
└── lua/custom/plugins/
    ├── init.lua         # Common plugins (Copilot, Neo-tree)
    ├── flutter.lua      # Flutter/Dart profile
    ├── python.lua       # Python profile
    └── svelte.lua       # Svelte/Web profile

Copy from this repository

If you've pushed your config to GitHub:

cd ~/.config/nvim
git remote set-url origin YOUR_FORK_URL
git pull

Or manually copy the lua/custom/ directory from your current setup.

7. Configure Node.js Path in Neovim

This is critical for GitHub Copilot to work!

The init.lua file should have this configuration (around lines 96-110):

-- ========================================================================
-- NODE.JS PATH CONFIGURATION (for GitHub Copilot and LSP servers)
-- ========================================================================
-- GitHub Copilot and some LSP servers require Node.js to be in PATH.
-- fnm doesn't add Node.js to Neovim's PATH automatically, so we do it here.
-- Using fnm aliases ensures this works even when Node.js version changes.
-- ========================================================================

-- Add fnm Node.js to PATH for Copilot and other Node.js-dependent plugins
local fnm_default_path = vim.fn.expand '~/.local/share/fnm/aliases/default/bin'
local fnm_multishells_path = vim.fn.expand '~/.local/share/fnm/node-versions/*/installation/bin'

if vim.fn.isdirectory(fnm_default_path) == 1 then
  vim.env.PATH = fnm_default_path .. ':' .. vim.env.PATH
elseif vim.fn.glob(fnm_multishells_path) ~= '' then
  local node_path = vim.fn.glob(fnm_multishells_path)
  vim.env.PATH = node_path .. ':' .. vim.env.PATH
end

This ensures Neovim can find Node.js even when it's not in the shell PATH.

8. First Launch - Install Plugins

Open Neovim

nvim

On first launch:

  1. lazy.nvim will automatically install all plugins
  2. Wait for plugins to finish installing (watch the bottom of the screen)
  3. You may see some errors - this is normal on first launch

Manually sync plugins (if needed)

:Lazy sync

Wait for completion, then restart Neovim:

:qa
nvim

9. Install LSP Servers and Tools via Mason

Open Mason

nvim
:Mason

Required Tools

These should auto-install via mason-tool-installer, but verify:

Common:

  • lua-language-server (lua_ls)
  • stylua

Flutter:

  • dart-language-server (dartls)

Python:

  • pyright
  • ruff

Svelte/Web:

  • svelte-language-server
  • typescript-language-server (ts_ls)
  • tailwindcss-language-server
  • prettier

Manual Installation (if needed)

In Mason, navigate to a tool and press:

  • i - Install
  • U - Update
  • X - Uninstall
  • g? - Help

10. Setup GitHub Copilot

Authenticate Copilot

nvim
:Copilot setup

Follow the prompts:

  1. It will give you a code
  2. Open the URL in your browser
  3. Enter the code
  4. Authorize GitHub Copilot

Verify Copilot works

:Copilot status

Should show: "Copilot: Ready"

11. Install Treesitter Parsers

Parsers should auto-install when you open files, but you can manually install:

:TSInstall dart python svelte typescript tsx javascript css html json lua vim vimdoc

Verify:

:TSInstallInfo

🔧 Configuration Summary

Shell Configuration (~/.zshrc)

Your ~/.zshrc should have these additions:

# fnm (Fast Node Manager) - for managing Node.js versions
eval "$(fnm env --use-on-cd)"

# Bun - Fast JavaScript runtime
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

Directory Structure After Installation

~/.config/nvim/
├── init.lua                    # Main Kickstart config (modified with Node.js PATH)
├── lazy-lock.json              # Plugin versions (auto-generated)
├── LICENSE.md
├── README.md
├── SETUP-GUIDE.md              # Profile setup guide
├── INSTALLATION.md             # This file
├── doc/
│   └── kickstart.txt
└── lua/
    ├── custom/
    │   └── plugins/
    │       ├── init.lua        # Common plugins (Copilot, Neo-tree)
    │       ├── flutter.lua     # Flutter profile
    │       ├── python.lua      # Python profile
    │       └── svelte.lua      # Svelte profile
    └── kickstart/
        └── plugins/
            ├── autopairs.lua
            ├── debug.lua
            ├── gitsigns.lua
            ├── indent_line.lua
            ├── lint.lua
            └── neo-tree.lua

~/.local/share/fnm/
├── aliases/
│   └── default/                # Default Node.js version
│       └── bin/
│           ├── node
│           └── npm
└── node-versions/
    └── v24.11.0/               # Actual Node.js installation

~/.bun/
└── bin/
    └── bun                     # Bun executable

~/.local/share/nvim/
├── lazy/                       # lazy.nvim plugin installations
└── mason/                      # Mason LSP/tool installations

🧪 Verification Checklist

After installation, verify everything works:

Check Node.js Setup

# Should all work:
which node
node --version
which npm
npm --version
which fnm
fnm list

Check Bun Setup

which bun
bun --version

Check Neovim

nvim --version
# Should be v0.10.0+

Test in Neovim

# Open Neovim
nvim

# Check Node.js is in PATH
:echo $PATH
# Should include: /Users/YOUR_USERNAME/.local/share/fnm/aliases/default/bin

# Check Copilot
:Copilot status
# Should show: Ready

# Check plugins
:Lazy
# All plugins should be loaded or available

# Check Mason
:Mason
# All tools should be installed

# Check LSP
:checkhealth lsp
# Should show no errors

🔄 Updating Tools

Update Node.js

# Install new LTS version
fnm install --lts

# Set as default
fnm default lts-latest

# Old versions are kept, you can switch back:
fnm use 22  # if you need an older version

The fnm alias system means Neovim automatically uses the new version without config changes!

Update Bun

bun upgrade

Update Neovim Plugins

:Lazy update

Update Mason Tools

:Mason
# Press 'U' to update all tools

Update Neovim

brew upgrade neovim

🐛 Troubleshooting

Copilot says "Node.js not found"

  1. Check Node.js is installed: which node
  2. Check fnm is in PATH: which fnm
  3. Verify init.lua has Node.js PATH configuration (see step 7)
  4. Restart Neovim completely

LSP not loading

:LspInfo          # Check if attached
:checkhealth lsp  # Check for issues
:Mason            # Verify tool is installed

Plugins not loading

:Lazy check
:Lazy clean
:Lazy sync

Format-on-save not working

:ConformInfo      # Check formatter config
:Mason            # Verify formatter installed

Treesitter syntax highlighting broken

:TSUpdate         # Update all parsers
:checkhealth nvim-treesitter

🚀 Platform-Specific Notes

Linux

  • Use your package manager instead of Homebrew
  • fnm install: curl -fsSL https://fnm.vercel.app/install | bash
  • Bun works the same way
  • Shell config goes in ~/.bashrc or ~/.zshrc

Windows (WSL)

  • Use WSL2 with Ubuntu/Debian
  • Follow Linux instructions above
  • Make sure Neovim is installed in WSL, not Windows

Windows (Native)

  • Use Scoop or Chocolatey instead of Homebrew
  • fnm Windows install: winget install Schniz.fnm
  • Bun: powershell -c "irm bun.sh/install.ps1 | iex"
  • Config goes in ~\AppData\Local\nvim\

📚 Additional Resources

📝 Quick Setup Script

For experienced users, here's a one-liner (review before running!):

# Install Homebrew (if needed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install all tools
brew install neovim fnm && \
fnm install --lts && \
fnm default lts-latest && \
curl -fsSL https://bun.sh/install | bash

# Add to ~/.zshrc
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
echo 'export BUN_INSTALL="$HOME/.bun"' >> ~/.zshrc
echo 'export PATH="$BUN_INSTALL/bin:$PATH"' >> ~/.zshrc

# Clone Kickstart
git clone https://github.com/nvim-lua/kickstart.nvim.git ~/.config/nvim

# Copy your custom plugins
# (You need to do this manually from your backup/repo)

# Launch Neovim
source ~/.zshrc
nvim

Then in Neovim:

  1. Wait for plugins to install
  2. Run :Copilot setup
  3. Restart Neovim
  4. Done! 🎉

Last Updated: October 29, 2025 Neovim Version: v0.11.4 Node.js Version: v24.11.0 LTS Bun Version: 1.3.1