doc: added installation instructions
This commit is contained in:
Anup Sebastian
parent
dd2e744f0b
commit
0ccbc8cb03
|
|
@ -0,0 +1,527 @@
|
|||
# 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)
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
### 2. Install Neovim
|
||||
```bash
|
||||
brew install neovim
|
||||
```
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
brew install fnm
|
||||
```
|
||||
|
||||
#### Configure fnm in your shell
|
||||
Add to `~/.zshrc`:
|
||||
```bash
|
||||
# fnm (Fast Node Manager) - for managing Node.js versions
|
||||
eval "$(fnm env --use-on-cd)"
|
||||
```
|
||||
|
||||
Reload your shell:
|
||||
```bash
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
#### Install Node.js LTS
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
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):
|
||||
```bash
|
||||
# Bun - Fast JavaScript runtime
|
||||
export BUN_INSTALL="$HOME/.bun"
|
||||
export PATH="$BUN_INSTALL/bin:$PATH"
|
||||
```
|
||||
|
||||
Reload your shell:
|
||||
```bash
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
bun --version
|
||||
# Should show 1.3.x or similar
|
||||
```
|
||||
|
||||
### 5. Clone Kickstart.nvim Configuration
|
||||
|
||||
#### Backup existing config (if you have one)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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):
|
||||
|
||||
```lua
|
||||
-- ========================================================================
|
||||
-- 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
|
||||
```bash
|
||||
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)
|
||||
```vim
|
||||
:Lazy sync
|
||||
```
|
||||
|
||||
Wait for completion, then restart Neovim:
|
||||
```vim
|
||||
:qa
|
||||
nvim
|
||||
```
|
||||
|
||||
### 9. Install LSP Servers and Tools via Mason
|
||||
|
||||
#### Open Mason
|
||||
```vim
|
||||
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
|
||||
```vim
|
||||
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
|
||||
```vim
|
||||
:Copilot status
|
||||
```
|
||||
|
||||
Should show: "Copilot: Ready"
|
||||
|
||||
### 11. Install Treesitter Parsers
|
||||
|
||||
Parsers should auto-install when you open files, but you can manually install:
|
||||
|
||||
```vim
|
||||
:TSInstall dart python svelte typescript tsx javascript css html json lua vim vimdoc
|
||||
```
|
||||
|
||||
Verify:
|
||||
```vim
|
||||
:TSInstallInfo
|
||||
```
|
||||
|
||||
## 🔧 Configuration Summary
|
||||
|
||||
### Shell Configuration (~/.zshrc)
|
||||
|
||||
Your `~/.zshrc` should have these additions:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Should all work:
|
||||
which node
|
||||
node --version
|
||||
which npm
|
||||
npm --version
|
||||
which fnm
|
||||
fnm list
|
||||
```
|
||||
|
||||
### Check Bun Setup
|
||||
```bash
|
||||
which bun
|
||||
bun --version
|
||||
```
|
||||
|
||||
### Check Neovim
|
||||
```bash
|
||||
nvim --version
|
||||
# Should be v0.10.0+
|
||||
```
|
||||
|
||||
### Test in Neovim
|
||||
```vim
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
bun upgrade
|
||||
```
|
||||
|
||||
### Update Neovim Plugins
|
||||
```vim
|
||||
:Lazy update
|
||||
```
|
||||
|
||||
### Update Mason Tools
|
||||
```vim
|
||||
:Mason
|
||||
# Press 'U' to update all tools
|
||||
```
|
||||
|
||||
### Update Neovim
|
||||
```bash
|
||||
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
|
||||
```vim
|
||||
:LspInfo # Check if attached
|
||||
:checkhealth lsp # Check for issues
|
||||
:Mason # Verify tool is installed
|
||||
```
|
||||
|
||||
### Plugins not loading
|
||||
```vim
|
||||
:Lazy check
|
||||
:Lazy clean
|
||||
:Lazy sync
|
||||
```
|
||||
|
||||
### Format-on-save not working
|
||||
```vim
|
||||
:ConformInfo # Check formatter config
|
||||
:Mason # Verify formatter installed
|
||||
```
|
||||
|
||||
### Treesitter syntax highlighting broken
|
||||
```vim
|
||||
: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
|
||||
|
||||
- **Kickstart.nvim**: https://github.com/nvim-lua/kickstart.nvim
|
||||
- **fnm**: https://github.com/Schniz/fnm
|
||||
- **Bun**: https://bun.sh
|
||||
- **Mason**: https://github.com/williamboman/mason.nvim
|
||||
- **lazy.nvim**: https://github.com/folke/lazy.nvim
|
||||
- **Neovim**: https://neovim.io
|
||||
|
||||
## 📝 Quick Setup Script
|
||||
|
||||
For experienced users, here's a one-liner (review before running!):
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Loading…
Reference in New Issue